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PREFACE 



About This Book 



This book is a programmer's guide to the music architecture in version 3 of 
QuickTime for Macintosh and Windows. It describes all the featiires introduced, 
added, or changed in the QuickTime music architecture since QuickTime 
version 1.5, and therefore supersedes all existing documentation for versions 
1.6.1, 2.0, 2.1, and 2.5. 



Book Structure 



Chapter 1 begins with an overview of the new features in the QuickTime music 
architecture (QTMA), introducing you to its basic concepts. Some programming 
examples are also provided. Chapter 2 offers a QuickTime music architecture 
reference, listing all the constants, data types, and functions in the QuickTime 3 
QTMA. Appendix A is a General MIDI reference with tables listing General 
MIDI instrument numbers and General MIDI drum kit numbers. 



Conventions Used in This Book 



This book provides various conventions to present information. Words that 
require special treatment appear in specific fonts or font styles. 

Special Fonts 

All code listings, reserved words, and the names of actual data structures, 
constants, fields, parameters, and functions are shown in Letter Gothic (this is 
Letter Gothic). 

Types of Notes 

There are several types of notes used in this book. 
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Note 

A note like this contains information that is interesting but 
not essential to an understanding of the main text. ♦ 

IMPORTANT 

A note like this contains especially important information 
that is essential for an imderstanding of the main text. ▲ 

▲ W/lRNING 

A warning like this indicates potential problems that you 
should be aware of as you design your software. Failure to 
heed these warnings could result in system crashes or loss 
of data. ▲ 



Development Environment 



The functions described in this book are available using C interfaces. How you 
access them depends on the development environment you are using. 

Code listings in this book are shown in ANSI C. They suggest methods of using 
various functions and illustrate techniques for accomplishing particular tasks. 
Although most code listings have been compiled and tested, Apple Computer 
Inc., does not intend for you to use these code samples in your application. 
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This chapter describes the QuickTime music architecture (QTMA), which 
allows QuickTime movies, applications, and other software to play individual 
musical notes, sequences of notes, and a broad range of sounds from a variety 
of instruments and synthesizers. With QTMA, you can also import Standard 
MIDI files (SMF) and convert them into QuickTime movies for easy playback. 

Because the QTMA is component-based and implemented as Component 
Manager components, your application can take advantage of a nirmber of 
QTMA components for extensibility. For example, you can use the QuickTime 
music synthesizer, which is a software-based music synthesizer included with 
QuickTime, to generate soimds or music out of a computer's built-in audio 
device. You can also use the General MIDI component for playing music on a 
General MIDI device attached to a serial port. 

Before reading this chapter, you should already be familiar with QuickTime and 
QuickTime components. In order to create or use any component, your 

application must use the Component Manager. If you are not familiar with the 
Component Manager, see Chapter 6 of Inside Macintosh: More Macintosh Toolbox. 

You need to read this chapter if you are writing an application that creates 
QuickTime movies and you want to incorporate music tracks as part of the 
movie, either by importing MIDI files or by programmatically generating 
musical sequences. If you want to create a music component or add an 
instrument to the existing library of instruments, you also need to read this 
chapter These capabilities are explained in the section "Using the QuickTime 
Music Architecture" (page 31). If you are creating new instrimients, you should 
be familiar with QT atoms and atom containers, which are described in 
Chapter 1, "Movie Toolbox" in QuickTime 3 Reference. 

Chapter 2 in this book contains an extensive reference section, which describes 
the constants, data t5^es, and fimctions of the QTMA. 
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Introduction to QuickTime Music Architecture 



The QuickTime music architecture is implemented as Component Manager 
components, which is the standard mechanism that QuickTime uses to provide 
extensibility. 

QTMA components exist both in QuickTime for Macintosh and QuickTime for 
Windows. Note that in QuickTime 3 for Windows, MIDI output is not yet 
supported; only the QuickTime music synthesizer is available. 

Different QTMA components are used by a QuickTime movie, depending on if 
you are playing music or soimds through the computer's built-in audio device, 
or if you are controlling, for example, a MIDI S3mthesizer. During playback of a 
QuickTime movie, the music media handler component isolates your 
application and the Movie Toolbox from the details of how to actually play a 
music track. The task of processing the data in a music track is taken care of for 
you by the media handler through Movie Toolbox calls. 

The following sections provide overviews of these components and their 
capabilities. 

Overview of QTMA Components 

The QuickTime music architecture includes the following components: 

■ the note allocator, which plays individual musical notes 

■ the time player, which plays sequences of musical notes 

■ the music media handler, which processes data in music tracks of QuickTime 
movies 

■ the QuickTime music synthesizer, a software-based music synthesizer 
included with QuickTime, which plays soimds using the built-in audio of a 
Macintosh or Mac OS-based computer or the sound card or built-in audio 
circuitry of other computers 

■ the General MIDI s}mthesizer, which plays music on a General MIDI device 

connected to the computer 

■ the MIDI synthesizer component, which controls a MIDI synthesizer 
connected to the computer using a single MIDI channel 
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■ other music components that provide interfaces to specific synthesizers 

These components are described in more detail in the following sections. 
Figure 1-1 illustrates the relationships among the various QTMA components. 



Figure 1-1 How Quicl<Time music architecture components worl< together 
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Note Allocator Component 

You use the note allocator component to play individual notes. Your 
application can specify which musical instrument sound to use and exactly 
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which music S5mthesizer to play the notes on. The note allocator component can 
also display an Instniment Picker, which allows the user to choose instruments. 
The note allocator, unlike the tune player, provides no timing-related features to 
manage a sequence of notes. Its features are similar to a music component, 
although more generalized. Typically, an application opens a connection to the 
note allocator, which in turn sends messages to the music component. An 
application or movie music track can incorporate any number of musical 
timbres or parts. 

To play a single note, your application must open a connection to the note 
allocator component and call NANewNoteChannel with a note request — typically 
to request a standard instrument within the General MIDI library of 
instruments. A note channel is similar in some ways to a Sound Manager soimd 
channel in that it needs to be created and disposed of, and can receive various 
commands. The note allocator provides an application-level interface for 
requesting note channels with particular attributes. The client specifies the 
desired polyphony and the desired tone. The note allocator returns a note 
channel that best satisfies the request. 

With an open note channel, an application can call NAPlayNote while specifying 
the note's pitch and velocity. The note is played and continues to play until a 
second call to NAPlayNote is made specifying the same pitch but with a velocity 
of zero. The velocity of zero causes the note to stop. The note allocator functions 
let you play individual notes, apply a controller change, apply a knob change, 
select an instrument based on a required tone, and modify or change the 
instrument type on an existing note channel. 

There are calls for registering and unregistering a music component. As part of 
registration, the MIDI connections, if applicable, are specified. There is also a 
call for querying the note allocator for registered music components, so that an 
application can offer a selection of the existing devices to the user. 

Tune Player Component 

The tune player component can accept entire sequences of musical notes and 
play them start to finish, asynchronously, with no further need for application 
intervention. It can also play portions of a sequence. An additional sequence or 
sequence section may be queued-up while one is currently being played. 
Queuing sequences provides a seamless way to transition between sections. 

The tune player negotiates with the note allocator to determine which music 
component to use and allocates the necessary note channels. The tune player 
handles all aspects of timing, as defined by ihe sequence of music events. For 
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more information about music events and the event sequence that is required to 
produce music in a QuickTime movie track, see iJrie section "About QuickTime 
Music Events" (page 19). 

The tune player also provides services to set the volume and to stop and restart 
an active sequence. 

Note 

If your application simply wants to play background 
music, it may be easier to use the QuickTime Movie 
Toolbox, rather than call the tune player directly. ♦ 

Music Components Included in QuickTime 

Individual music components act as device drivers for each type of S5mthesizer 
attached to a particular computer. Three music components are included in 
QuickTime: 

■ the QuickTime music synthesizer component, for playing music out of a 
computer's built-in speaker 

■ the General MIDI S5mthesizer component, for playing music on a General 
MIDI device attached to a serial port. 

■ the MIDI synthesizer component, which allows QuickTime to control a 
synthesizer that is connected to a single MIDI channel. 

Developers can add other music components for specific hardware and 
software S5mthesizers. To better understand the role of a music component, see 
"The QuickTime Music Synthesizer Component" (page 16). 

Applications do not usually call music components directly. Instead, the note 

allocator or tune player handles music component interactions. Music 
components are mainly of interest to application developers who want to access 
the low-level fimctionality of S5mthesiz;ers and for developers of synthesizers 
(internal cards, MIDI devices, or software algorithms) who want to make the 
capabilities of their synthesizers available to QuickTime. 

In order for an application to call a music component directly, you must first 
allocate a note channel and then use NAGetNoteChannel Info and 
NAGetRegi steredMusi cDevi ce to get the specific music component and part 
number. 

You can use music component fimctions to 
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■ obtain specific information about a synthesizer 

■ find an instrument that best fits a requested type of sound 

■ play a note with a specified pitch and volume 

■ change knob values to alter instrument sounds 

Other functions are for handling instruments and synthesizer parts. You can use 
these functions to initialize a part to a specified instniment and to get lists of 
available instrument and drum kit names. You can also get detailed information 
about each instrument from the synthesizer and get information about and set 
knobs and controllers. 

Instrument Components and Atomic Instruments 

When initialized, the note allocator searches for components of type ' i nst ' . 
These components may report a list of atomic instruments. They are called 
atomic instruments, because you create them with QT atoms. (QT atoms are 
described in Chapter 1, "Movie Toolbox," of QuickTime 3 Reference). These 
sounds can be embedded in a QuickTime movie, passed via a call to 
QuickTime, or dropped into the System Folder. 

QuickTime 3 provides a public format for atomic instruments. Using the 
QuickTime calls for manipulating atoms, you construct in memory a 
hierarchical tree of atoms with the data that describes the instrument (see 
Figiire 1-2). The tree of atoms lives inside an atom container. There is one and 
only one root atom per container. Each atom has a four-character (32-bit) type, 
and a 32-bit ID. Each atom may be either an internal node or a leaf atom with 
data. 
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Figure 1-2 An atomic instrument atom container 
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The QuickTime Music Synthesizer Component 

The QuickTime music synthesizer component is a software-based synthesizer 
that is included with QuickTime. The soimd it generates can be sent to the 
built-in speaker of a Macintosh or Mac OS-based computer or to the soimd card 
or built-in audio circuitry of other computers. 

The QuickTime music synthesizer includes a variety of built-in instrviments in 
the atomic instrument format. You can also create new instruments for the 
synthesizer. The instruments used by the QuickTime music S5mthesizer are 
known as atomic instnmients, because they are defined using QuickTime 
atoms. 

The instruments of the QuickTime music sjmthesizer are described by a set of 
knobs and one or more waveforms. 

IMPORTANT 

To play notes, you normally use the note allocator or tune 
player component. These components invoke the 
QuickTime music synthesizer or another music component 
to generate sounds. If you need to use the QuickTime 
music synthesizer directly, you must open an instance of 
the note allocator, which is responsible for finding the 
instrument components that best fit the criteria for 
instruments, and leave it open while using the synthesizer. 
If the note allocator is not open, the QuickTime music 
synthesizer may be forced to repeatedly open and close 
connections to the note allocator, which can greatly 
diminish performance. This reconraiendation may also 
apply to other music components that use the note 
allocator's instrument library routines. ▲ 

Atomic instruments for the QmckTime music synthesizer are defined by some 
waveform data and a set of knob values. Knobs provide a way to modify the 
instrument soimd — for example, by applying a tremolo. Typically, the 
instrument has a full list of knobs, and if the instrument contains more than a 
single sample, each sample contains values for several knobs that are tuned for 
that particular sample. In this context, a sample is defined as a short recording 
of a musical sound. 

Knobs can be specified either by index or by ID. A nonzero value in the high 
byte of the 24-bit number field of an instrument knob record or l<noblD field of a 
knob description record indicates that it is an ID. The knob index ranges from 1 



Introduction to QuickTime IVIusic Architecture 



CHAPTER 1 

QuickTime IViusic Architecture 



to the number of knobs; the ID is an arbitrary number. You should generally 
access knobs by ID, because knob IDs do not change over different versions of 
the QuickTime software whereas knob index values might. 

The General MIDI Synthesizer Component 

The General MIDI S3mthesizer component controls General MIDI devices. These 
devices support 24 voices of pol5^hony, and each of their MIDI channels can 
access any number of voices. A user can choose this sjmthesizer in llie 
QuickTime Settings control panel. For information about the QuickTime 
Settings control panel, see "QuickTime Settings Music Panel" (page 32). 

The MIDI Synthesizer Component 

The MIDI synthesizer component allows QuickTime to control a synthesizer 
coruiected to a single MIDI channel. It works with any S5mthesizer that can be 
controlled through MIDI. 

The MIDI synthesizer component does not get information about the 
synthesizer instrimients. Instead, it simply lists available instruments as 
"Instrument 1," "Instrument 2," and so on — up to "Instrument 128." 

The Base Instrument Component 

When you provide additional sotmds for the QuickTime music synthesizer, you 
can simplify the creation of the necessary instrument resources by using the 
base instrviment component. To create an instrument component, you create a 
component alias whose target is the base instrument component. The 
component alias's data resources specify the capabilities of an instrument, while 
the code resource of the base instrimient component handles all of the 
component requests sent to the instrument component. 

For information about component aliases, see Chapter 2, "Component 
Manager," in QuickTime 3 Reference. 

The Generic Music Component 

To use a new hardware or software S5mthesizer with the QuickTime music 
architecture, you need a music component that serves as a device driver for that 
synthesizer and that can play notes on the synthesizer. You can simplify the 
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creation of a music component by using the services of the generic music 
component. To create a music component, you create several resources, for 
which you get much of the data by calling functions of the generic music 
component, and implement functions that the generic music component calls 
when necessary. When a music component is a client of the generic music 
component, it handles only a few component calls from applications and more 
relatively simple calls from the generic music component. 

MIDI Components 

A MIDI component provides a standard interface between the note allocator 
component and a particular MIDI transport system, such as the Apple MIDI 

Manager or the Open Music System^M (QMS) developed by Opcode Systems, 
Inc. Each MIDI component supports both input and output of MIDI streams. 

The QuickTime music architecture includes MIDI components for the following 
MIDI transport systems: 

■ The MIDI Manager developed by Apple Computer, Inc. 

■ The Open Music System (OMS) developed by Opcode Systems, Inc. 

■ The FreeMIDI system extension for the Mac OS developed by Mark of the 
Unicorn, Inc. 

Hardware and software developers can provide additional MIDI components. 
For example, the developer of a multiport serial card can provide a MIDI 
component that supports direct MIDI input an.d output using the card. Other 
MIDI components can support MIDI transport systems for operating systems 
other than the Mac OS. 

To use a MIDI component, you use the fimctions described in "MIDI 
Component Functions" (page 162). To create a new MIDI component, you 
create a component that implements these functions. 

Note 

QuickTime 3 for Windows does not yet support MIDI 
output; only the QuickTime music synthesizer is 
available. ♦ 
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About QuickTime Music Events 



Music events specify the instruments and notes of a musical composition. A 
group of music events is called a sequence. A sequence of events may define a 
range of instruments and their characteristics and the notes and rests that, when 
interpreted, produce the musical composition. 

The event sequence required to produce music is usually contained in a 
QuickTime movie track, which uses a media handler to provide access to the 
tune player, or an application, which passes them directly to the tune player. 
QuickTime interprets and plays the music from the sequence data. 

The events described in this section initialize and modify soimd-producing 
music devices and define the notes and rests to be played. 

Events are constructed as a group of long words. The uppermost 4 bits (nibble) 
of an event's long word defines its type, as shown in Table 1-1. 



Table 1-1 Event types 



Number of 

First nibble long words Event type 

OOOx 1 Rest 

OOlx 1 Note 

01 Ox 1 Controller 

Ollx 1 Marker 

1000 2 (reserved) 

1001 2 Extended note 

1010 2 Extended controller 

1011 2 Knob 
1100 2 (reserved) 
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Event types (continued) 



First nibble 



Number of 
long words 



Event type 



1101 



2 



(reserved) 
(reserved) 



1110 



2 



nil 



n 



General 



Durations of notes and rests are specified in units of the tune player's time scale 
(default 1/600 second). For example, consider the musical fragment shown in 
Figiire 1-3. 



Figure 1-3 A music fragment 




Assuming 120 beats per minute, and a tune player's scale of 600, each quarter 
note's duration is 300. Figure 1-4 shows a graphical representation of note and 
rest data. 
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Figure 1-4 Duration of notes and rests 
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The general event specifies the types of instruments or sounds used for the 
subsequent note events. The note event causes a specific instrument, previously 
defined by a general event, to play a note at a particular pitch and velocity for a 
specified duration of time. 

Additional event types allow sequences to apply controller effects to 
instruments, define rests, and modify instrument knob values. The entire 
sequence is closed with a marker event. 

In most cases, the standard note and controller events (two long words) are 
sufficient for an application's requirements. The extended note event provides 
wider pitch range and fractional pitch values. The extended controller event 
expands the number of instruments and controller values over that allowed by 
a controller event. 

The following sections describe the event types in detail. 



Note Event and Extended Note Event 

The standard note event (Figure 1-5) supports most music requirements. The 
note event allows up to 32 parts, nirmbered to 31, and support pitches from 2 
octaves below middle C to 3 octaves above. The extended note event 
(Figure 1-6) provides a wider range of pitch values, microtonal values to define 
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any pitch, and extended note duration. The extended note event requires two 
long words; the standard note event requires only one. 



Figure 1-5 
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Table 1-2 Contents of a note event 

note event type First nibble value = 1 X 

Part number Unique part identifier 

Pitch Ntimeric value of 0-63, mapped to 32-95 

Velocity 0-127, = no audible response (but used to 

indicate a NOTE OFF) 

Duration Specifies how long to play the note in imits 

defined by the media time scale or tune 
player time scale 

The part number bit field contains the unique part identifier initially used 
during the TuneSetHeader call. 

The pitch bit field allows a range of 0-63, which is mapped to the values 32-95 
representing the traditional equal tempered scale. For example, the value 28 
(mapped to 60) is middle C. 

The velocity bit field allows a range of 0-127. A velocity value of produces 
silence. 

The duration bit field defines the niimber of units of time during which the part 
will play the note. The units of time are defined by the media time scale or tune 
player time scale. 

Use this macro call to stuff the note event's long word: 

qtma_StuffNoteEvent(x , instrument, pitch, volume, duration) 

Use these macro calls to extract fields from the note event's long word: 
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qtma_Instrument(x) 
qtma_NotePitch(x) 
qtma_NoteVel oci ty (x) 
qtma_NoteVol ume(x) 
qtma_NoteDuration(x) 



Figure 1-6 Extended note event 
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Table 1-3 Contents of an extended note event 



Extended note event type 

Part ntimber 

Pitch 



Velocity 
Ehiration 

Event tail 



First nibble value = 1001 
Unique part identifier 

0-127 standard pitch, 60 = middle C 0x01 . 00 ... 
Ox7F. 00 allowing 256 microtonal divisions 
between each notes in the traditional equal 

tempered scale 

0-127 where = no audible response (but used 
to indicate a NOTE OFF) 

Specifies how long to play the note in units 
defined by media time scale or tune player time 
scale 

First nibble of last word = lOXX 



The part number bit field contains the unique part identifier initially used 

during the TuneSetHeader call. 

If the pitch bit field is less than 128, it is interpreted as an integer pitch where 60 
is middle C. If the pitch is 128 or greater, it is treated as a fixed pitch. 

Microtonal pitch values are produced when the 15 bits of the pitch field are 
split. The upper 7 bits define the standard equal tempered note and the lower 8 
bits define 256 microtonal divisions between the standard notes. 
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Use this macro call to stuff the extended note event's long words: 
qtma_StuffXNoteEvent(wl , w2, instrument, pitch, volume, duration) 

Use these macro calls to extract fields from the extended note event's long 
words: 

qtma_XInstrument(m, 1) 
qtma_XNotePi tch (m , 1) 
qtma_XNoteVel oci ty (m , 1) 
qtma_XNoteVol ume(m, 1) 
qtma_XNoteDuration(m, 1) 



The rest event (Figure 1-7) specifies the period of time, defined by either the 
media time scale or the time player time scale, imtil the next event in the 
sequence is played. 

Figure 1-7 Rest event 
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Table 1-4 



Contents of a rest event 



Rest event type 
Diiration 



First nibble value = OOOX 

Specifies the number of units of time until the next 
note event is played in units defined by media time 
scale or tune player time scale 



Use this macro call to stuff the rest event's long word: 



qtma_Stuff Rest Event (x , duration) 



Use this macro call to extract the rest event's duration value: 



qtma_RestDurati on (x) 
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Note 

Rest events are not used to cause silence in a sequence, but 
to define the start of subsequent events. ♦ 

Marker Event 

The marker event has three subtypes. The end marker event (Figure 1-8) marks 
the end of a series of events. The beat marker event marks the beat and the 
tempo marker event indicates the tempo. 

Figure 1-8 IVIarlor event of subtype end 
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Table 1-5 Contents of a marker event 

Marker event type First nibble value = 1 1 X 

Subt5^e 8-bit imsigned subtype 

Value 16-bit signed value 

The marker subtype bit field contains zero for an end marker (kMarkerEventEnd), 
1 for a beat marker (kMarkerEventBeat), or 2 for a tempo marker 

(kMarkerEventTempo). 

The value bit field varies according to the subtype: 

■ For an end marker event, a value of means stop; any other value is 
reserved. 

■ For a beat marker event, a value of is a single beat (a quarter note); any 
other value indicates the number of fractions of a beat in 1 / 65536 beat. 

■ For a tempo marker event, the value is the same as a beat marker, but 
indicates that a tempo event should be computed (based on where the next 
beat or tempo marker is) and emitted upon export. 

Use this macro call to stuff the marker event's long word: 
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qtma_StuffMarl<erEvent(x , marl<erType, markerValue) 

Use these macro calls to extract fields from the marker events long word: 

qtma_MarkerSubtype(x) 
qtma_MarkerVal ue(x) 

Controller Event and Extended Controller Event 

The controller event (Figure 1-9) changes the value of a controller on a specified 
part. The extended controller event (Figure 1-10) allows parts and controllers 
beyond the range of the standard controller event. 



Figure 1-9 Controller event 



type.3 


1 part. 5 


controller.8 


value. 16 


1 O 




xxxx xxxx 


xxxx xxxx| xxxx xxxx 



Table 1 -6 Contents of a controller event 

controller event type First nibble value = 01 OX 

Part Unique part identifier 

Controller Controller to be applied to instrument 

Value 8.8 bit fixed-point signed controller specific 

value 

For a list of currently supported controller types see "Controller Numbers" 
(page 56). 

The part field contains the unique part identifier initially used during the 

TuneSetHeader call. 

The controller bit field is a value that describes the type of controller used by 
the part. 

The value bit field is specific to the selected controller. 
Use this macro call to stuff the controller event's long word: 
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qtma_StuffControl Event(x, instrument, control, value) 

Use these macro calls to extract fields from the controller event's long word: 

qtma_Instrunient(x) 
qtma_Control Control ler(x) 
qtma_Control Val ue(x) 



Figure 1-10 Extended controller event 
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Table 1-7 Contents of an extended controller event 



Extended controller type First nibble value = 1010 

Part Instrument index for controller 

Controller Controller for instrument 

Value Signed controller specific value 

Event tail First nibble of last word = 1 X X 

The part field contains the imique part identifier initially used during the 
TuneSetHeader call. 

The controller bit field contains a value that describes the type of controller to 
be used by the part. 

The value bit field is specific to the selected controller. 

Use this macro call to stuff the extended controller event's long words: 

_Stuff XControl EventCwl , w2, instrument, control, value) 

Use these macro calls to extract fields from the extended controller event's long 
words: 
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qtma_XInstrument(m, 1) 
qtma_XControl Control 1 er(m, 1) 
qtma_XControl Val ue(m, 1) 



General Event 

For events longer than two words, you use the general event with a subtjrpe. 
Figure 1-11 illustrates the contents of a general event. 



Figure 1-11 A note request general event 
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Table 1-8 Contents of a general event 



General event type 
Part number 
Event length 
Data words 
Subtjrpe 
Event length 
Event tail 



First nibble value =1111 

Unique part identifier 

Head is number of words in event 

Depends on subtype 

8-bit unsigned subt5rpe 

tail must be identical to head 

First nibble of last word = 1 1 XX 



The part number bit field contains a unique identifier that is later used to match 
note, knob, and controller events to a specific part. For example, to play a note 
the application uses the part number to specify which instrument will play the 
note. The general event allows part numbers of up to 12 bits. The standard note 
and controller events allow part numbers of up to 5 bits; the extended note and 
extended controller events allow 12-bit part numbers. 
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The event length bit fields contained in the first and last words of the message 
are identical and are used as a message format check and to move back and 
forth through the message. The lengths include the head and tail; the smallest 
length is 2. 

The data words field is a variable length field containing information imique to 
the subt5^e of the general event. The subtype bit field indicates the subtype of 
general event. There are nine subtypes: 

■ Anote request general event (kGeneral EventNoteRequest) has a subtype of 1. 
It encapsulates the note request data structure used to define the instrument 
or part. It is used in the tune header. 

■ Apart key general event (KGeneral Event Part Key) has a subtj^e of 4. It sets a 
pitch offset for the entire part so that every subsequent note played on that 
part will be altered in pitch by the specified amount. 

■ Atune difference general event (kGeneral EventTuneDi fference) has a subt5^e 
of 5. It contains a standard sequence, with end marker, for the tune difference 
of a sequence piece. Using a tune difference event is similar to using key 
frames with compressed video sequences. (This subt5^e halts QuickTime 2.0 
music). 

■ An atomic instrument general event (kGeneral EventAtomi c Instrument) has a 
subt5^e of 6. It encapsulates an atomic instrument. It is used in the time 
header. It may be used in place of the kGeneral EventNoteRequest. 

■ Aknob general event (kGeneral EventKnob) has a subt5^e of 7. It contains 
knob ID/knob value pairs. The smallest event is four long words. 

■ A MIDI channel general event (kGeneral EventMIDI Channel) has a subtype of 
8. It is used in a tune header. One long word identifies the MIDI channel it 
originally came from. 

■ Apart change general event (kGeneral EventPartChange) has a subtype of 9. It 
is used in a tune sequence where one long word identifies the tune part that 
can now take over the part's note channel. (This subtype halts QuickTime 2.0 
music.) 

■ Ano-op general event (kGeneral EventNoOp) has a subt5^e of 10. It does 
nothing in the current version of QuickTime. 

■ A notes-used general event (kGeneral EventUsedNotes) has a subtype of 11. It 
is four long words specifying which MIDI notes are actually used. It is used 
in the tune header. 
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Use these macro calls to stuff the general event's head and tail long words, but 
not the structures described above: 

qtma_StuffGeneral Event(wl , w2 , instrument, subType, length) 

Macros are used to extract field values from the event's head and tail long 
words. 

qtma_XInstrument(m, 1) 
qtma_General Subtype(m, 1) 
qtma_General Length(m, 1) 

Knob Event 

The knob event is used to modify a particular knob or knobs within a specified 
part. 

Figure 1-12 Knob event 
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Table 1-9 



Contents of a l<nob event 



Knob event type 



First nibble value = 1111 (general event), 
subt5^e 7 

Length of the event will be 2(#knobs+l) 

Unique part identifier 

Knob ID within specified part 

Knob value 



Length 
Part 



Knob ID 



Knob value 



Event tail 



First nibble of last word = 11 XX, subt5^e 7 



The part field contains the unique part identifier initially used during the 

TuneSetHeader call. 

The knob number bit field identifies the knob to be changed. 

The 32-bit value composed of the lower 16-bit and upper 16-bit field values is 
used to alter the specified knob. 



The QuickTime Music Architecture provides functions that allow applications 
to control all aspects of playing music tracks and generating musical sounds in 
QuickTime movies. 

This section discusses a few of the more common operations your application 
can perform with the QTMA, and it has been divided into the following 
subsections: 

■ "QuickTime Settings Music Panel" describes changes to the music panel in 
the QuickTime Settings control panel in QuickTime 3. 

■ "Converting MIDI Data to a QuickTime Music Track Using MoviePlayer" 
describes how you can open a standard MIDI file and convert it into a 
QuickTime music track. 

■ "Importing a Standard MIDI File As a Movie Using the Movie Toolbox" 
shows how you can read a Standard MIDI File (SMF) and convert it into a 
QuickTime movie. 
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■ "Playing Notes With the Note Allocator" discusses how you can play notes 
with the note allocator component. A routine is also shown for playing notes 
in a piano sound with the note allocator component. 



QuickTime Settings Music Panel 

In QuickTime 3, the Music panel in the QuickTime Settings control panel has 
been completely revised. It now allows for greater flexibility in setting up 
QTMA synthesizer configurations, including multiple MIDI ports provided by 
QMS, FreeMIDI, or the MIDI Manager and multiple synthesizers. Figure 1-13 
shows the new panel. 



Figure 1-13 The new music panel in tlie Quicl<Time Settings control panel 
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Note that the user can select from a list of available S5mthesizers for playing 
music and MIDI files. The user can also configure the S5mthesizers in the list by 
clicking the Edit List button. 

Figure 1-14 displays the dialog box that appears when the user clicks the Edit 
List button. 
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Note 

The screen displayed in Figure 1-14 is preliminary and 
subject to change. The functionality of configuring 
S5mthesizers in the list, however, will not change in 
QuickTime 3. ♦ 



Figure 1-14 Tlie Edit List popup dialog box for adding, removing, and configuring 
QTMA synthesizers 
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If a General MIDI S5mthesizer is selected in the S5mthesizer pop-up menu, the 
user must also specify which MIDI port the synthesizer is connected to, as 
shown in Figure 1-14. If there is no MIDI system installed (for example, OMS, 
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FreeMIDI, or MIDI Manager on the Macintosh), General MIDI does not appear 
in the Synthesizer pop-up menu. 

QuickTime 3 includes one additional S5mthesizer type: a generic "MIDI 
Synthesizer," which can be any MIDI device that lives on a single channel. 
Figure 1-14 shows the control panel set up for a single MIDI S5mthesizer on 
MIDI channel 5. 

Converting MIDI Data to a QuickTime Music Track Using 
MoviePlayer 

The MoviePlayer and SimpleText applications allow you to open a standard 
MIDI file and convert it into a QuickTime music track. After the file is 
converted, the application prompts you to save the converted file as a 
QuickTime movie. Once saved, a movie controller is displayed and you can 
play the music. 

Importing a Standard MIDI File As a Movie Using the Movie 
Toolbox 

Most music content exists in Standard MIDI Files (SMF), which have a standard 
format. All sequencing and composition programs let you save or export files in 
this format. QuickTime provides facilities for reading an SMF and converting it 
into a QuickTime movie. During any kind of conversion, the SMF is assumed to 
be scored for a General MIDI device, and MIDI channel 10 is assumed to be a 
drum track. 

The conversion to a QuickTime movie can happen in one of several ways. 
Because it is implemented in a QuickTime 'eat ' component, the conversion 
happens automatically in most cases. Any application that uses the 
StandardGetFile routine to open a movie can also open 'Midi ' files 
transparently, and can transparently paste Clipboard contents of type 'Midi' 
into a movie shown with the standard movie controller. 

To explicitly convert a file or handle into a movie, your application can use the 
Movie Toolbox routines ConvertFileToMovieFile and PasteHandlelntoMovie, 
respectively. 

When authoring MIDI files to be converted to QuickTime music movies, two 
MIDI system-exclusive messages can be used for more precise control of the 
MIDI import process. Note that QuickTime data is divided into media samples. 



Using the QuickTime l\/lusic Architecture 



CHAPTER 1 



QuickTime IViusic Architecture 



Within video tracks, each video frame is considered one sample; in music 
tracks, each sample can contain several seconds worth of musical information. 

■ FO 11 00 01 XX yy zz F7 sets the maximum size of each media sample to the 
21-bit number xxyyzz. (MIDI data bytes have the high bit clear, so they have 
only seven bits of number.) This message can occur anywhere in an SMF. 

■ FO 11 00 02 F7 marks an immediate sample break; it ends the current 
sample and starts a new one. All messages after a sample break message are 
placed in a new media sample. 

Applications can define their own system-exclusive messages of the form FO 11 
7F WW XX yy zz ... application-defined data ... F7, where ww xx yy zz is the 
application's unique signature with the high bits cleared. This is guaranteed not 
to interfere with Apple's or any other manufacturer's use of system-exclusive 
codes. 

Playing Notes With tlie Note Allocator 

Playing a few notes with the note allocator component is simple and 
straightforward. To play notes that have a piano soimd, for example, you need 
to open up the note allocator component, allocate a note channel with a request 
for piano, and play. When you've finished playing notes, you dispose of the 
note channel and close the note allocator component. The code to accomplish 
this is shown in Listing 1-2. Before working through the code, you need to look 
at some important related data structures. 

Note-Related Data Structures 

A note channel is analogous to a soimd channel in that you allocate it, issue 
commands to it to produce sound, and close it when you're done. To specify 
details about the note channel, you use a data structure called aNoteRequest 
(see Listing 1-1). 

Listing 1-1 Note-related data structures 



struct NoteRequest { 

NoteRequestlnfo info; // in post-QuickTime 2.0 only 

ToneDescri pti on tone; 

); 
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struct NoteRequestlnfo { 
UInt8 flags; 
UlntS reserved; 
short polyphony; 
Fixed typi cal Polyphony ; 

}; 

struct ToneDescri pti on { 

OSType synthesi zerType ; 

Str31 synthesi zerName ; 

Str31 i nstrumentName ; 

long i nstrumentNumber ; 

long gmNumber; 

}; 

The next two fields specify the probable polyphony that the note channel will 
be used for. Polyphony means, literally, many sounds. A pol5^hony of 5 means 
that five notes can be playing simultaneously. The polyphony field enables 
QTMA to make sure that the allocated note channel can play all the notes you 
need. The typical pol y phony field is a fixed-point number that should be set to 
the average number of voices the note channel will play; it may be whole or 
fractional. Some music components use this field to adjust the mixing level for a 
good volume. If in doubt, set the typical pol yphony field to 0X00010000. 

The ToneDescri pti on structure is used throughout QTMA to specify a musical 
instrument sound in a device-independent fashion. This structure's 
synthesi zerType and synthesi zerName fields can request a particular S5mthesizer 
to play notes on. Usually, they're set to 0, meaning "choose the best General 
MIDI synthesizer." The gmNumber field indicates the General MIDI (GM) 
instrument or drum kit sound, which may be any of 135 such sounds supported 
by many S5mthesizer manufacturers. (All these soimds are available on a 
General MIDI Sound Module.) The GM instruments are numbered 1 through 
128, and the seven drum kits are numbered 16385 and higher. For S5mthesizers 
that accept soimds outside the GM library, you can use the i nstrumentName and 
i nstrumentNumber fields to specify some other sound. 

Playing Piano Sounds With the Note Allocator 

The routine in Listing 1-2 plays notes in a piano sound with the note allocator 
component. 
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Listing 1-2 



Playing notes witli tlie note allocator component 



void PI aySomeNotes(void) 



NoteAl 1 ocator 
NoteChannel 
NoteRequest 
ComponentResul t 
long 



nr ; 
thi sError ; 
t, i ; 



na ; 



nc ; 



na = 0; 
nc = 0; 

// Open up the note allocator. 

na = OpenDef aul tComponentC kNoteAl 1 ocatorType , 0); 
if (!na) 

goto goHome; 

// Fill out a NoteRequest using NAStuf fToneDescri pti on to help, and 
// allocate a NoteChannel. 
nr . i nf . f 1 ags = ; 
nr . i nf . reserved = ; 

nr . i nfo . polyphony = 2; // simultaneous tones 

nr . i nf . typi cal Pol yphony = 0x00010000; // usually just one note 
thisError = NAStuf fToneDescri pti on ( na , 1, &nr.tone); // 1 is piano 
thisError = NANewNoteChannel (na , &nr, &nc); 
if (thisError || !nc) 
goto goHome; 

// If we've gotten this far, OK to play some musical notes. Lovely. 
NAPlayNote(na, nc, 60, 80); // middle C at velocity 80 
Delay(40, &t); // delay 2/3 of a second 

NAPl ayNote( na , nc, 60, 0); // middle C at velocity 0: end note 

Delay(40, &t); // delay 2/3 of a second 

// Obligatory do-loop of rising tones 

for (i =60; i <= 84; i++) { 

NAPl ayNote(na , nc, i, 80); // pitch i at velocity 80 

NAPl ayNote(na , nc, i+7, 80); // pitch i+7 (musical fifth) at 



DelaydO, &t); 



// velocity 80 

// delay 1/6 of a second 
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NAPl ayNote(na , nc, i, 0); // pitch i at velocity 0: end note 
NAPl ayNote( na , nc, i+7, 0); // pitch i+7 at velocity 0: 

// end note 

} 

goHome : 

if ( n c ) 

NADi sposeNoteChannel ( na , nc); 
if (na) 

CI oseComponent ( na ) ; 

} 

You start by calling OpenDefaul tComponent to open a connection to the note 
allocator. If this routine returns 0, the component wasn't opened, most likely 
because QTMA wasn't present. Next, you fill in the NoteRequestlnfo and 
ToneDescri pti on structures, calling the note allocator's NAStuf fToneDescri pti on 
routine and passing it the GM instrument number for piano. This routine fills in 
the gmNumber field and also fills in the other ToneDescri pti on fields with sensible 
values, such as the instrtiment's name in text form in the i nstrunientNanie field. 
(The routine can be useful for converting a GM instrument ntimber to its text 
equivalent.) 

After allocating the note channel with NANewNoteChannel , you call NAPl ayNote to 
play each note. Notice the last two parameters to NAPl ayNote: 

ComponentResul t NAPl ayNote( NoteAl 1 ocator na, NoteChannel nc, 
long pitch, long velocity); 

The value of the pitch parameter is an integer from 1 to 127, where 60 is middle 
C, 61 is C sharp, and 59 is C flat, or B. Similarly, 69 is concert A and is played at 
a nominal audio frequency of 440 Hz. 

The vel oci ty parameter's value is also an integer from 1 to 127, or 0. A velocity 
of 1 corresponds to just barely touching the musical keyboard, and 127 indicates 
that the key was struck as hard as possible. Different velocities produce tones of 
different volumes from the S5mthesizer. A velocity of means the key was 
released; the note stops or fades out, as appropriate to the kind of sound being 
played. 

You stop the notes at this point after delaying an appropriate amount of time 
with a call to the Del ay routine. Finally, you dispose of the note channel and 
close the note allocator component. 



Using the QuickTime l\/lusic Architecture 



CHAPTER 2 



Music Architecture Reference 



This chapter describes the constants, data structures, functions, and result codes 
provided by QuickTime music architecture. 



Constants 



This section describes the constants provided by QuickTime music architecture. 



Atom Types for Atomic Instruments 

These constants specify the t5^es of atoms used to build atomic instruments. 
Atomic instruments are described in "Instrument Components and Atomic 
Instriiments" (page 14). 

enum I 



kaiToneDescType 


= 'tone' 


kai Note Request I nfoType 


= 'ntrq' 


kai KnobLi stType 


= 'knbl ' 


kai KeyRangeInf oType 


= ' si nf ' 


kai Sampl eDescType 


= 'sdsc' 


kai Sampl eDataType 


= 'sdat' 


kai InstRefType 


= ' i ref ' 


kai InstlnfoType 


= ' i i n f ' 


kai Pi ctType 


= 'pict' 


kaiWriterType 


= '©wrt' 


kai Copyri ghtType 


= '©cpy' 


kai OtherStrType 


= 'str ' 



1; 
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Constant descriptions 

l<aiToneDescType A tone atom, which describes the tone. It contains a tone 
description structure (page 75). 

I<ai NoteRequestlnfoType 

A note request information atom, which contains a note 
request information structure (page 85). The note request 
information structure includes information about a tone 
that is not in the tone description. Use a note request 
information atom when embedding an instrument in a 
sample description of a QuickTime movie. If this atom is 
absent, QuickTime assumes "reasonable" values for 
polyphony. 

I<ai KnobLi stType A knob list atom, which specifies values for one or more 
knobs. It contains an instrimient knob list structure 
(page 72). Use it with a custom instrument, a modified 
built-in instrument, or as part of a sample. 

I<ai KeyRangelnfoType 

A key range information atom contains several other 
atoms. It also refers, via an ID, to one or more sibling 
sample info (kai Sampl einf oType) atoms. Use a key range 
information atom to include a sampled sound in an atomic 
instrument. 

l<aiSampleDescType A sample description atom, which contains an atomic 
instrument sample description structure (page 72). 

A sample data atom, which contains the actual audio data. 

An instnrment reference atom, which contains a tone 
description to be modified by a knob list atom. 

An instrument information atom, which contains four 
optional atoms with information for the instrument About 
box. 



kai Sampl eDataType 
l<ai InstRefType 

l<ai InstlnfoType 



l<ai Pi ctType 



kaiWriterType 



l<ai Copyri ghtType 



kai OtherStrType 



A picture atom that includes the graphic used in the 
instrument About box. 

A text atom that has the author information used in the 
instrument About box. 

A text atom that has the copyright information used in the 
instrument About box. 

A text atom that has additional information for the 
instrument About box. 
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kaiSamplelnfoType A text atom that contains a sample data 
(ki aSampl eDataType) atom. 

Instrument Knob Flags 

These flags are used in the knobFlags field of an instrimient knob list structure 
(page 72) to indicate what to do if a requested knob is not in the list. 

enum { 

kInstKnobMi ssi ngUnknown = 0, 

kInstKnobMi ssi ngDef aul t = 1 << 

1; 

Constant descriptions 

kInstKnobMi ssi ngUnknown 

If the requested knob is not in the list, do not set its value. 

kInstKnobMi ssingDefault 

If the requested knob is not in the list, use its default value. 

Loop Type Constants 

You can use these constants in the 1 oopType field of an atomic instrument 
sample description structure (page 72) to indicate the type of loop you want. 

enum { 

kMusi cLoopTypeNormal = 0, 

kMusi cLoopTypePal i ndrome = 1 

): 

Constant descriptions 

kMusi CLoopTypeNormal 

Use a regular loop. 

kMusi cLoopTypePal i ndrome 

Use a back-and-forth loop. 
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Music Component Type 

Use this constant to specify a QuickTime music component. 

enum { 

kMusi cComponentType = 'musi' 

}; 

Constant description 

kMusi cComponentType 

The type of any QTML music component. 

Synthesizer Type Constants 

You can use these constants in a tone description structure (page 75) to specify 
the t5^e of synthesizer you want to produce the tone. 

enum { 

kSoftSynthComponentSubType = 'ss 

kGMSynthComponentSubType = 'gm 

}; 

Constant descriptions 

kSoftSynthComponentSubType 

Use the QuickTime music S5mthesizer. This is the built-in 
synthesizer. 

kGMSynthComponentSubType 

Use the General MIDI synthesizer. 



Synthesizer Description Flags 

These flags describe various characteristics of a S5mthesizer. They are used in 
the flags field of the synthesizer description structure (page 73). 

enum { 

kSynthesi zerDynami cVoi ce = 1, 

kSynthesizerUsesMIDIPort = 2, 

kSynthesi zerMi crotone = 4, 
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kSynthesizerHasSamples 


= 8, 


kSynthesi zerMi xed Drums 


= 6, 


kSynthesi zer Software 


= 32, 


kSynthesi zerHardware 


= 64, 


kSynthesi zer DynamicChannel 


= 128, 


kSynthesi zerHogsSystemChannel 


= 256, 


kSynthesi zerSl owSetPart 


= 1024, 


kSynthesi zer Of fl i ne 


= 4096, 


kSynthesi zerGM 


= 16384 



Constant descriptions 

kSynthesi zerDynamicVoice 

Voices can be assigned to parts on the fly with this 
synthesizer (otherwise, polyphony is very important). 

kSynthesi zerUsesMIDIPort 

This synthesizer must be patched through a MIDI system, 
such as the MIDI Manager or OMS. 

kSynthesi zerMicrotone 

This synthesizer can play microtonal scales. 

kSynthesi zerHasSamples 

This sjmthesizer has some use for sampled audio data. 

kSynthesi zer Mi xed Drums 

Any part of this synthesizer can play drvim parts. 

kSynthesi zer Software 

This synthesizer is implemented in main CPU software and 
uses CPU cycles. 

kSynthesi zer Hardware 

This sjmthesizer is a hardware device, not a software 
synthesizer or MIDI device. 

kSynthesi zerDynami cChannel 

This S5mthesizer can move any part to any channel or 
disable each part. For devices only. 

kSynthesi zerHogsSystemChannel 

Even if the kSynthesi zerDynami cChannel bit is set, this 
synthesizer always responds on its system channel. For 
MIDI devices only. 
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kSynthesizerSl owSetPa rt 

This synthesizer does not respond rapidly to the various set 
part and set part instrument calls. 

i<Synthesi zerOf f 1 i ne 

This synthesizer can enter an offline synthesis mode. 

l<Synthesi zerGM This synthesizer is a General MIDI device. 



Synthesizer Knob ID Constants 



These constants specify knob IDs for the QuickTime music synthesizer. These 
constants are all of the form kQJMSKnobknobnamelD. For example, 
l<QTMSKnobVol umeLFODel aylD is the ID constant for the Vol umeLFODel ay knob. 



enum { 

kQTMSKnobEnvlAttackTimelD = 0x02000027, 

kQTMSKnobEnvlDecayTimelD = 0x02000028, 

kQTMSKnobEnvlExpOptionsID = 0x02000020, 

kQTMSKnobEnvlRel easeTimelD = 0x02000020, 

kQTMSKnobEnvlSustainlnfinitelD = 0x0200002B, 

kQTMSKnobEnvlSustainLevel ID = 0x02000029, 

kQTMSKnobEnvlSustainTimelD = 0x0200002A, 

kQTMSKnobEnv2AttackTimeID = 0x0200002E, 

kQTMSKnobEnv2DecayTimeID = Ox0200002F, 

kQTMSKnobEnv2Exp0ptionsID = 0x02000034, 

kQTMSKnobEnv2Rel easeTimelD = 0x02000033, 

kQTMSKnobEnv2SustainInfiniteID = 0x02000032, 

kQTMSKnobEnv2SustainLevel ID = 0x02000030, 

kQTMSKnobEnv2SustainTimeID = 0x02000031, 

kQTMSKnobExclusionGroupID = Ox0200001C, 
kQTMSKnobPi IterFrequencyEnvelopeDepthlD 

= 0x0200003B, 

kQTMSKnobFi IterFrequencyEnvelopelD 

kQTMSKnobFi 1 terKeyFol 1 owID 
kQTMSKnobFi IterQEnvel opeDepthID 



kQTMSKnobFi 1 terQEnvel opelD 
kQTMSKnobFi IterQID 
kQTMSKnobFi IterTransposelD 
kQTMSKnobLastlDPlusl 



= 0x0200003A, 

= 0x02000037, 
= 0x02000030, 
/* reverb threshhold */ 
= 0x0200003C, 
= 0x02000039, 
= 0x02000038, 
= 0x0200003F 
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kQTMSKnobPitchEnvelopeDeptlilD 
kQTMSKnobPitchEnvel ope ID 
kQTMSKnobPitchLFODelaylD 
kQTMSKnobPitchLFODepthFromWIieel ID 

kQTMSKnobPitchLFODepthID 
kQTMSKnobPitchLFOOffsetID 
kQTMSKnobPitchLFOPeriodID 
kQTMSKnobPitcliLFOQuantizelD 

kQTMSKnobPitchLFORampTimelD 
kQTMSKnobPitchLFOShapelD 
kQTMSKnobPitcliSensiti vitylD 
kQTMSKnobPitcliTransposelD 

kQTMSKnobReverbThreslioldID 
kQTMSKnobStartID 
kQTMSKnobStereoDefaul tPanID 
kQTMSKnobStereoPosi ti on Key Seal i ngID 
kQTMSKnobSustai n Inf i ni telD 
kQTMSKnobSustainTimelD 
kQTMSKnobVelocityHighID 
kQTMSKnobVelocityLowID 
kQTMSKnobVelocity Sensitivity ID 
kQTMSKnobVol umeAttackTimelD 

kQTMSKnobVol umeDecayTimelD 

kQTMSKnobVol umeExpOptionsID 
kQTMSKnobVol umeLFQDel ay ID 
kQTMSKnobVol umeLFQDepthFromWIieel ID 
kQTMSKnobVol umeLFQDepth ID 
kQTMSKnobVol umeLFQPeriodID 
kQTMSKnobVol umeLFQRampTimelD 
kQTMSKnobVol umeLFQShape ID 
kQTMSKnobVol umeLFQStereoID 
kQTMSKnobVol umeQveral 1 ID 
kQTMSKnobVol umeRel ease Key Seal ingID 
kQTMSKnobVol umeRel easeTimelD 

kQTMSKnobVol umeSustai nLevel ID 



0x02000036, /* filter */ 
0x02000035, 
0x02000013, 
0x02000025, 
' volume nnv again */ 
0x02000017, 
0x02000018, 
0x02000015, 
0x02000018, 

' stereo related knobs */ 
0x02000014, 
0x02000016, 
0x02000023, 
0x02000012, 

' sample can override */ 
0x0200003E, 
0x02000000, 
0x02000019, 
0x0200001A, 
0x0200001E, 
0x0200001D, 
0x02000021, 
0x02000020, 
0x02000022, 
0x02000001, 

' sample can override */ 
0x02000002, 

' sample can override */ 
0x02000026, /* envl */ 
0x02000007, 
0x02000024, 
0x02000008, 
0x02000009, 
0x02000008, 
0x0200000A, 
0x0200001F, 
0x0200000C, 
0x02000005, 
0x02000006, 

' sample can override */ 
0x02000003, 
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/* sample can override */ 



l<QTMSKnobVol umeVel oci tyl27ID 
l<QTMSKnobVol umeVel ocityl6ID 



= 0x02000000, 
= 0x02000011, 



/* pitch related l<nobs */ 



l<QTMSKnobVol umeVel oci ty32ID 
kQTMSKnobVol umeVel oci ty 64 ID 
l<QTMSKnobVol umeVel ocity96ID 



= 0x02000010, 
= 0x0200000F, 
= 0x0200000E 



Constant descriptions 



l<QTMSKnobEnvlAttacl<TimeID 



Specifies the attack time of the first general-purpose 
envelope. This is the number of milliseconds between the 
start of a note and the maximum value of the attack. 



Specifies the decay time of the first general-purpose 
envelope. This is the number of milliseconds between the 
time the attack is completed and the time the envelope 
level is reduced to the sustain level. 



Specifies whether segments of the envelope are treated as 
exponential curves. Bits 0, 1, 2, and 3 of the knob value 
specify the interpretation of the attack, decay, sustain, and 
release segments of the envelope, respectively. If any of 
these bits is 0, the level of the corresponding segment 
changes linearly from its initial to final value during the 
time interval specified by the corresponding envelope time 
knob. If any of these bits is nonzero, the level of the 
corresponding segment changes exponentially during the 
time interval specified by the corresponding envelope time 
knob. During an exponential decrease, the level changes 
from maximum amplitude (no attenuation) to 
approximately 1 /65536th of maximum amplitude (96 dB of 
attenuation) during the time interval specified by the 
corresponding envelope time knob, and afterward the level 
immediately becomes 0. 



Specifies the release time of the first general-purpose 
envelope. 



l<QTMSKnobEnvlDecayTimeID 



kQTMSKnobEnvlExpOptionsID 



l<QTMSKnobEnvlRel easeTimelD 
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kQTMSKnobEnvlSustai ninf i ni telD 

Specifies infinite sustain for the first general-purpose 
envelope. If the value of this knob is true, the knob 
overrides the kQTMSKnobEnvlSustai nTinielD knob and causes 
the sustain to last, at undiminished level. Instruments like 
an organ have infinite sustain. 

kQTMSKnobEnvlSustainLevel ID 

Specifies the sustain level of the first general-purpose 
envelope. This is the percentage of full volume that the 
sample is initially played at after the decay time has 
elapsed. 

kQTMSKnobEnvlSustai nTiniel D 

Specifies the sustain time of the first general-purpose 
envelope. This is the number of milliseconds it takes for the 
sample to soften to 90% of its sustain level. This softening 
occurs in an exponential fashion, so it never actually 
reaches complete silence. This is used for instrviments like a 
piano, which gradually soften over time even while the key 
is held down. 

kQTMSKnobEnv2AttackTimeID 

Specifies the attack time of the second general-purpose 
envelope. This is the number of milliseconds between the 
start of a note and the maximtim value of the attack. 
Percussive sotmds usually have zero attack time; gentler 
sounds may have short attack times. Long attack times are 
usually used for special effects. 

kQTMSKnobEnvZDecayTimelD 

Specifies the decay time of the second general-purpose 
envelope. This is the number of milliseconds between the 
time the attack is completed and the time the sample is 
reduced in voliraie to the sustain level. 

kQTMSKnobEnv2ExpQpti onsID 

Specifies whether segments of the envelope are treated as 
exponential curves. Bits 0, 1, 2, and 3 of the knob value 
specify the interpretation of the attack, decay, sustain, and 
release segments of the envelope, respectively. If any of 
these bits is 0, the level of the corresponding segment 
changes linearly from its initial to final value during the 
time interval specified by the corresponding envelope time 
knob. If any of these bits is nonzero, the level of the 
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corresponding segment changes exponentially during the 
time interval specified by the corresponding envelope time 
knob. During an exponential decrease the level changes 
from maximum amplitude (no attenuation) to 
approximately 1 /65536th of maximum amplitude (96 dB of 
attenuation) during the time interval specified by the 
corresponding envelope time knob, and afterward the level 
immediately becomes 0. 

l<QTMSKnobEnv2Rel easeTimelD 

Specifies the release time of the second general-purpose 
envelope. This is the niimber of milliseconds it takes for the 
soimd to soften down to silence after the key is released. 

l<QTMSKnobEnv2SustainInf ini telD 

Specifies infinite sustain for the second general-purpose 
envelope. If the value of this knob is true, the knob 
overrides the kQTMSKnobEnv2SustainTimeID knob and causes 
the sustain to last, at undiminished volume, until the end of 
the sample. Instrimients like an organ have infinite sustain. 

l<QTMSKnobEnv2SustainLevel ID 

Specifies the sustain level of the first general-purpose 
envelope. This is the percentage of full volume that the 
sample is initially played at after the decay time has 
elapsed. 

kQTMSKnobEnv2SustainTimeID 

Specifies the sustain time of the second general-purpose 
envelope. This is the number of milliseconds it takes for the 
sample to soften to 90% of its sustain level. This softening 
occurs in an exponential fashion, so it never actually 
reaches complete silence. This is used for instruments like a 
piano, which gradually soften over time even while the key 
is held down. 

l<QTMSKnobExcl usionGroupID 

Specifies an exclusion group. Within an instrimient, no two 
notes with the same exclusion group number, excepting 
exclusion group, will ever sound simultaneously.This knob 
is generally used only as an override knob within a key 
range. (Note that the key range is not an entire instrirment.) 
It is useful for simulating certain mechanical instruments in 
which the same mechanism produces different soimds. For 
example, in a drum kit, the open high hat and the closed 
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high hat are played on the same piece of metal. If you 
assign both soimds to the same exclusion group, playing a 
closed high hat sound immediately silences any currently 
playing open high hat sounds. 

kQTMSKnobFi IterFrequencyEnvel ope Depth ID 

Controls the depth of the envelope for the filter frequency. 
This is an 8.8 signed fixed-point value that specifies the 
niimber of semitones the frequency is altered when its 
envelope (specified by the 
kQTMSKnobFi IterFrequencyEnvelopelD knob) 
is at maximtmn amplitude. If the value of the 
kQTMSKnobFi 1 terFrequencyEnvel opelD knob is 0, which 
specifies not to use an envelope to affect filter frequency, 
the kQTMSKnobFi 1 terFrequencyEnvel opeOeptlnlD knob is 
ignored. 

kQTMSKnobFi 1 terFrequencyEnvel ope ID 

Specifies which of the two general-purpose envelopes to 
use to affect the filter frequency, or not to use an envelope 
to affect filter frequency. If the value of this knob is 0, no 
envelope is used. If the value of this knob is 1 or 2, the 
corresponding general-purpose envelope is used. 

KQTMSKnobFilterKeyFol 1 owID 

Specifies how closely the frequency of the filter follows the 
note being played. The emphasis note is determined by the 
following formula, expressed in MIDI notes: 

EmphasisNote = {PlayedNote - 60) * 
(kQTMSKnobFilterKeyFollowID / 100) - 60 - 
kQTMSKnobFi IterTransposelD 

kQTMSKnobFi IterQEnvelopeDepth ID 

Controls the depth of the envelope for the emphasis ("Q") 
of the filter. This is an 8.8 signed fixed-point value that 
specifies the emphasis is altered when its envelope 
(specified by the kQTMSKnobFi 1 terQEnvel opelD knob) is at 
maximum amplitude. If the value of the 
kQTMSKnobFi 1 terQEnvel ope ID knob is 0, which specifies not 
to use an envelope to affect filter frequency, the 
kQTMSKnobFi 1 terQEnvel opeDepthID knob is ignored. 

kQTMSKnobFi 1 terQEnvel ope ID 

Specifies which of the two general-purpose envelopes to 



Constants 



49 



CHAPTER 2 

Music Architecture Reference 



use to affect the emphasis ("Q") of the filter, or not to use 
an envelope to affect the emphasis. If the value of this knob 
is 0, no envelope is used. If the value of this knob is 1 or 2, 
the corresponding general-purpose envelope is used. 

l<QTMSKnobFilterQID 

Specifies the emphasis ("Q") of the filter The value must be 
in the range to 65536, inclusive, where specifies no 
emphasis and disables the filter, and 65536 specifies 
relatively steep emphasis, but not so steep that it 
approaches feedback. 

kQTMSKnobFi IterTransposelD 

Specifies a transposition, in semitones, of the frequency of 
the filter. The emphasis note is determined by the following 
formula: 

EmphasisNote = {PlayedNote - 60) * 

(kQTMSKnobFilterKeyFollowID / 100) - 60 - 
kQTMSKnobFi IterTransposelD 

kQTMSKnobPi tchEnvel opeDepthID 

Specifies the depth of the pitch envelope. This is an 8.8 

signed fixed-point value that specifies the number of 

semitones the pitch is altered when the envelope for the 

pitch (specified by the kQTMSKnobPi tchEnvel ope ID knob) is at 

maximum amplitude. If the value of the 

kQTMSKnobPi tchEnvel opelD knob is 0, which specifies not to 

use an envelope to affect pitch, the 

kQTMSKnobPi tchEnvel opeDepthID knob is ignored. 

kQTMSKnobPi tchEnvel ope ID 

Specifies which of the two general-purpose envelopes to 
use to affect pitch, or not to use an envelope to affect pitch. 
If the value of this knob is 0, no envelope is used. If the 
value of this knob is 1 or 2, the corresponding 
general-piirpose envelope is used to affect pitch. 

kQTMSKnobPi tchLFQDel ay ID 

Specifies the delay for the pitch LFO. This is the nxmiber of 
milliseconds before the LFO takes effect. 

kQTMSKnobPi tchLFQDepthFromWheel ID 

Specifies the extent to which a synthesizer's modulation 
wheel (or the MIDI messages it generates) controls the 
depth of the pitch LFO. The value of this knob is multiplied 
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by the modulation wheel value (a value between to 1), 
and the result is added to the volume LFO depth specified 
by the kQTMSKnobPitchLFODepthID knob. Modulation wheel 
controllers and the MIDI messages they generate are most 
often used to create vibrato and tremolo effects. 

kQTMSKnobPitcliLFODepthID 

Specifies the depth of the pitch LFO. This is the number of 
seiiutones by which the pitch is altered by the LFO. A value 
of does not change the pitch. A value of 12 changes the 
pitch from an octave lower to an octave higher, with one 
exception: if the square up waveform is used for the LFO, 
the normal pitch is the minimum pitch. 

kQTMSKnobPitcliLFOOffsetID 

Specifies the LFO offset. This is a constant value; the imits 
are 8.8 semitones. It is added to the pitch, and is affected by 
the LFO delay and LFO ramp-up times. It is similar to 
transposition but subject to the LFO delay and LFO 
ramp-up times. 

kQTMSKnobPitcliLFOPeriodID 

Specifies the period for the pitch LFO. This is the 
wavelength of the LFO in milliseconds. (The LFO rate in 
Hz is 1000 / kQTMSKnobPitchLFOPeriodID). 

kQTMSKnobPitcliLFOQuantizelD 

To be provided 

kQTMSKnobPitcliLFORampTimelD 

Specifies the LFO ramp-up time. This is the number of 
milliseconds after the LFC3 delay that it takes for the LFO to 
reach full effect. 

kQTMSKnobPitcliLFOSIiapelD 

Specifies the waveform used for the LFO. The available 
waveforms are sine, triangle, sawtooth up, sawtooth down, 
square up, square up-and-down, and random. The sine and 
triangle shapes both produce a smooth rise and fall of the 
pitch. The sawtooth up produces a gradual increase in 
pitch followed by a sudden fall. The sawtooth down shape 
produces a sudden increase in pitch, followed by a gradual 
reduction. The square up and square up-and-down shapes 
apply a sudden pulsing to the pitch; the square up only 
makes the pitch higher, while the up-and-down variant 
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makes the sound higher and lower. The random shape 
applies random changes to the pitch, once per LFO period. 

l<QTMSKnobPitchSensi ti vi ty ID 

Specifies the pitch key scaling. This determines how much 
the pitch of the struck note affects the pitch of the played 
note. Typically, this is 100%, meaning that a change in 1 
semitone of the struck note produces a change in 1 
semitone of the played note. Setting this knob to zero 
causes every note to play at the same pitch. Setting it to 
50% allows for all notes within the quarter-tone scale (24 
notes per octave) to be played. 

l<QTMSKnobPi tchTransposelD 

Specifies a transposition for pitches. The value is the 
number of semitones to transpose; a positive value raises 
the pitch anda negative value lowers it. The value can be a 
real number; the fractional part of the value alters the pitch 
by an additional fraction of a semitone. For example, to 
raise the pitch of every note played on the instrument by an 
octave, set the transpose knob to 12.0. 

kQTMSKnobReverbThresholdlD 

To be provided 

l<QTMSKnobStartID 

To be provided 

l<QTMSKnobStereoDefaul t Pan ID 

Specifies the default pan position for stereo sound. If no 
pan controller is applied, this determines where in the 
stereo field notes for this instrument are played. 

kQTMSKnobStereoPosi ti on Key Seal i ngID 

Specifies the key scaling for stereo sound. Amoimt to 
modify the stereo placement of notes based upon pitch. At 
the highest setting, high pitched notes are placed 
completely in the right speaker, while low pitched notes 
are placed entirely in the left speaker. 

l<QTMSKnobSustai ninf i ni telD 

Specifies infinite sustain for the volume envelope. If the 
value of this knob is true, the knob overrides the 
kQTMSKnobSustai nTimelD knob and causes the sustain to last, 
at undiminished volume, until the end of the sample. 
Instruments like an organ have infinite sustain. 
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kQTMSKnobSustai nTinielD 

Specifies the sustain time of the volume envelope. This is 
the number of milliseconds it takes for the note to soften to 
90% of its sustain level. This softening occurs in an 
exponential fashion, so it never actually reaches complete 
silence. This is used for instruments like a piano, which 
gradually soften over time even while the key is held 
down. 

kQTMSKnobVelocityHighID 

Specifies the maximum velocity value that produces soimd 
for a particular note. If the velocity value is greater, the 
note does not sound. This can be used to assign different 
samples to be played for selected velocity ranges. 

kQTMSKnobVel ocityLowID 

Specifies the minimum velocity value that produces sound 
for a particular note. If the velocity value is less, the note 
does not soimd. This can be used to assign different 
samples to be played for selected velocity ranges. 

kQTMSKnobVel OCT tySensitivity ID 

Specifies velocity sensitivity, which determines how much 
the key velocity affects the volume of the note. This value is 
a percentage. At 100%, a velocity of 1 is nearly silent, and a 
velocity of 127 is full volume. At 50%, the volume range is 
from one fourth to three fourths. At 0%, any velocity of key 
strike produces a half volume note. If the value of this knob 
is negative, then the note plays more softly as the key is 
struck harder. 

kQTMSKnobVol umeAttackTimelD 

Specifies the attack time for the volume envelope. This is 
the number of milliseconds between the start of a note and 
maximum volume. Percussive sounds usually have zero 
attack time; gentler sounds may have short attack times. 
Long attack times are usually used for special effects. 

kQTMSKnobVol umeDecayTimelD 

Specifies the decay time for the volume envelope. This is 
the nxmiber of milliseconds between the time the attack is 
completed and the time the volume is reduced to the 
sustain level. 
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kQTMSKnobVol umeExpOpti ons I D 

Specifies whether segments of the volume envelope are 
treated as exponential curves. Bits 0, 1, 2, and 3 of the knob 
value specify the interpretation of the attack, decay, sustain, 
and release segments of the volume envelope, respectively. 
If any of these bits is 0, the volume level of the 
corresponding segment changes linearly from its initial to 
final value during the time interval specified by the 
corresponding envelope time knob. If any of these bits is 
nonzero, the volume level of the corresponding segment 
changes exponentially during the time interval specified by 
the corresponding envelope time knob. During an 
exponential decrease the volume level changes from full 
volume (no attenuation) to approximately 1/ 65536th of full 
volume (96 dB of attenuation) during the time interval 
specified the corresponding envelope time knob, and 
afterward the volume level inomediately becomes 0. 

l<QTMSKnobVolumeLFODelayID 

Specifies the delay for the volvime LFO. This is the number 
of milliseconds before the LFO takes effect. 

l<QTMSKnobVol umeLFODepthFromWheel ID 

Specifies the extent to which a synthesizer's modulation 
wheel (or the MIDI messages it generates) controls the 
depth of the volume LFO. The value of this knob is 
multiplied by the modulation wheel value (a value 
between to 1), and the result is added to the volume LFO 
depth specified by the kQTMSKnobVol umeLFODepthID knob. 
Modulation wheel controllers and the MIDI messages they 
generate are most often used to create vibrato and tremolo 
effects. 

kQTMSKnobVol umeLFODepthID 

Specifies the depth of the volume LFO. This is the amoimt, 
expressed as a percentage, by which the volirme is altered 
by the LFO. A value of does not change the volume. A 
value of 100 changes the volimie from complete silence to 
twice the volume specified by the envelope, with one 
exception: if the square up waveform is used for the LFO, 
the normal envelope voltime is the minimum volume. 

kQTMSKnobVol umeLFQPeriodlD 

Specifies the period for the volume LFO. This is the 
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wavelength of the LFO in milliseconds. (The LFO rate in 
Hz is 1000 / l<QTMSKnobPitchLFOPeriodID). 

kQTMSKnobVol umeLFORampTimelD 

Specifies the ramp-up time for the volvime LFO. This is the 
number of milliseconds after the LFO delay has elapsed 
that it takes for the LFO to reach full effect. 

kQTMSKnobVol umeLFOShape ID 

Specifies the waveform used for the LFO. The available 
waveforms are sine, triangle, sawtooth up, sawtooth down, 
square up, square up-and-down, and random. The sine and 
triangle shapes both produce a smooth rise and fall of the 
volume. The sawtooth up produces a gradual increase in 
volume followed by a sudden fall. The sawtooth down 
shape produces a sudden increase in volume, followed by a 
gradual reduction (often heard as a "ting" soimd). The 
square up and square up-and-down shapes apply a sudden 
pulsing to the volume; the square up only makes the sound 
louder, while the up-and-down variant makes the soimd 
louder and softer. The random shape applies random 
changes to the volume, once per LFO period. 

kQTMSKnobVol umeLFQStereoID 

If the synthesizer is producing stereo output and the value 
of this knob is 1, the LFO is applied in phase to one of the 
stereo channels and 180° out of phase to the other. This 
often causes a "vibration" effect within the stereo field. 

kQTMSKnobVol umeQveral 1 ID 

Specifies the overall volume of the instrument, in decibels. 
Increasing the value by 6 doubles the maximum amplitude 
of the signal, increasing the value by 12 quadruples it, and 
so on. 

kQTMSKnobVol umeRel easeKeyScal i ngID 

Specifies the release-time key scaling. Modifies the release 
time based on the key pitch. 

kQTMSKnobVol unieRel easeTinielD 

Specifies the release time of the volume envelope. This is 
the number of milliseconds it takes for the soimd to soften 
down to silence after the key is released. 

kQTMSKnobVol umeSustai nLevel ID 

Specifies the sustain level of the volume envelope. This is 
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the percentage of full volume that a note is initially played 
at after the decay time has elapsed. 



l<QTMSKnobVol umeVel oci tyl27I D 

To be provided 

kQTMSKnobVol umeVel oci tyl6ID 

To he provided 

l<QTMSKnobVol umeVel oci ty32I D 

To he provided 

kQTMSKnobVol umeVel oci ty 64 ID 

To he provided 

kQTMSKnobVol umeVel oci ty96I D 

To he provided 



Controller Numbers 



The controller numbers used by QuickTime are mostly identical to the standard 
MIDI controller numbers. These are signed 8.8 values. The full range, therefore, 
is -128.00 to 127+127/128 (or 0x8000 to 0x7FFF). 

All controls default to zero except for volume and pan. 

Pitch bend is specified in fractional semitones, which eliminates the restrictions 
of a pitch bend range. You can bend as far as you want, any time you want. 

The last 16 controllers (113-128) are global controllers. Global controllers 
respond when the part number is given as 0, indicating the entire synthesizer. 



enum { 



kControllerModulationWheel 



= 1, 
= 2, 
= 4, 
= 5, 

= 7, 
= 8, 
= 10, 
= 11, 
= 16, 
= 17, 
= 18, 
= 19, 



kControl 1 erBreath 

kControl 1 erFoot 



kControl lerPortamentoTi me 



kControl 1 erVol ume 

kControl 1 erBal ance 
kControl 1 erPan 



kControl ler Express ion 



kControl 1 erLeverl 
kControl 1 erLever2 
kControl 1 erLeverS 
kControl 1 erLever4 
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kControl 1 erLever5 = 80, 

kControl 1 erLever6 = 81, 

kControl 1 erLever7 = 82, 

kControl 1 erLeverS = 83, 

kControllerPitchBend = 32, 

kControl 1 erAfterToucli = 33, 

kControl 1 erSustai n = 64, 

kControl 1 erSostenuto = 66, 

kControl 1 erSoftPedal = 67, 

kControl 1 erReverb = 91, 

kControl 1 erTremol = 92, 

kControl 1 erChorus = 93, 

kControl 1 erCel este = 94, 

kControl 1 erPhaser = 95, 

kControllerEditPart = 113, 

kControl 1 erMasterTune = 114 



Constant descriptions 

kControl 1 erModul ati on Wheel 

This controller controls the modulation wheel. A 
modulation wheel adds a periodic change to the volvime or 
pitch of a soimding tone, depending on the modulation 
depth knobs. 

kControl 1 erBreath This controller controls breath. 

kControllerFoot This controller controls the foot pedal. 

kControl! erPortamentoTi me 

This controller adjusts the slur between notes. Set the time 
to to turn off portamento; there is no separate control to 
turn portamento on and off. 

kControllerVol ume This controller controls volirme. 

kControllerBalance This controller controls balance between channels. 

kControllerPan This controller controls balance on the QuickTime music 
synthesizer and some others. Values are 256-512, 
corresponding to left to right. 

kControl 1 er Express! on 

This controller provides a second volume control. 

kControl 1 erLeverl through kControl 1 erLeverS 

These are all general-purpose controllers. 
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kControllerPitchBend 



This controller bends the pitch. Pitch bend is specified in 
positive and negative semitones, with 7 bits per fraction. 



kControl 1 erAf terTouch 

This controller controls channel pressure. 

l<Control 1 erSustai n This controller controls the sustain effect. The value is a 
Boolean — ^positive for on, or negative for off. 

i<ControllerSostenuto 

This controller controls sostenuto . 

l<ControllerSoft Pedal 

This controller controls the soft pedal. 

kControllerReverb This controller controls reverb . 

kControl lerTremolo This controller controls tremolo. 

kControllerChorus This controller controls the amount of signal to feed to the 
chorus special effect unit. 

kControl lerCeleste This controller controls the amoimt of signal to feed to the 
celeste special effect imit. 

kControllerPhaser This controller controls the amount of signal to feed to the 
phaser special effect imit. 

kControl 1 erEdi t Part 



kControl lerMasterTune 

This controller offsets the entire synthesizer in pitch. 



These constants specify the maximum and minimum values for controllers. 



This controller sets the part number for which editing is 
occurring. For S5mthesizers that can edit only one part. 



Controller Range 



enum { 



kControl 1 erMaximum 
kControl 1 erMi nimum 



= 0x7FFF, 
= 0x8000 



Constant descriptions 



kControl 1 erMaxi mum 



The maximum value a controller can be set to. 
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kControl 1 erMi ni mum 

The minimiim value a controller can be set to. 



Drum Kit Numbers 

These constants specify the first and last drum kit numbers available to 
General MIDI drum kits. 

enum { 

kFi rstDrumkit = 16384, 

kLastDrumkit = ( kFi rstDrumki t + 128) 

1; 

Constant description 

kFi rstDrumkit The first number in the range of drum kit numbers, which 
corresponds to "no drum kit." The standard drum kit is 
kFi rstDrumKit+l=16385. 

kLastDrumkit The last number in the range of drum kit numbers. 

Tone Fit Flags 

These flags are returned by the Musi cFi ndTone function (page 133) to indicate 
how well an instrument matches the tone description. 



enum { 

kInstrumentMatchSynthesi zerType = 1, 

kInstrumentMatchSynthesi zerName = 2, 

kInstrumentMatchName = 4, 

kl nstrumentMatchlMumber = 8, 

kInstrumentMatchGMNumber = 16 



): 

Constant descriptions 

kInstrumentMatchSynthesi zerType 

The requested synthesizer type was found. 

kInstrumentMatchSynthesi zerName 

The particiilar instance of the synthesizer requested was 
found. 
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k Inst rumen tMatch Name 

The instrument name in the tone description matched an 
appropriate instrument on the synthesizer. 

I<lnst rumen tMatch Number 

The instnraient number in the tone description matched an 
appropriate instrument on the synthesizer. 

l<InstrumentMatchGMN umber 

The General MIDI equivalent was used to find an 
appropriate instrument on the synthesizer. 



Knob Flags 

Knob flags specify characteristics of a knob. They are used in the flags field of a 
knob description structure. Some flags describe the t5^e of values a knob takes 
and others describe the user interface. Knob flags are mutually exclusive, so 
only one should be set (all knob flag constants begin "kKnobType"). 

enum { 



kKnobReadOnly 




16, 




kKnoblnterrupt Unsafe 




32, 




kKnobKey rangeOverri de 




64, 




kKnobGroupSta rt 




128, 




kKnobFi xedPoi nt8 




1024, 




kknobFi xedPoi ntl6 




2048, 




kKnobTypeNumber 




<< 


12, 


kKnobTypeGroupName 




1 << 


12, 


kKnobTypeBool ean 




2 << 


12, 


kKnobTypeNote 




3 << 


12, 


kKnobTypePan 




4 « 


12, 


kKnobType Instrument 




5 << 


12, 


kKnobTypeSetti ng 




6 << 


12, 


kKnobTypeMi 1 1 i seconds 




7 << 


12, 


kKnobType Per cent age 




8 << 


12, 


kKnobTypeHertz 




9 << 


12, 


kKnobTypeButton 




10 << 


12 



}; 



60 



Constants 



CHAPTER 2 

Music Architecture Reference 



Constant descriptions 

kKnobReadOnl y The knob value cannot be changed by the user or with a set 
knob call. 

kKnob Interrupt Unsafe 

Alter this knob only from foreground task time. 

kKnobKeyrangeOverri de 

The knob can be overridden within a single key range 
(software synthesizer only). 

kKnobGroupStart The knob is first in some logical group of knobs . 

kKnobFixed Points Interpret knob numbers as fixed-point 8-bit. 

kKnobFixedPointie Interpret knob numbers as fixed-point 16-bit. 

kKnobTypeNumber The knob value is a numerical value. 

kKnobTypeGroupName The name of the knob is reaUy a group name for display 
purposes. 

kKnobTypeBool ean The knob is an on/ off knob. If the range of the knob (as 
specified by the low value and high value in the knob 
description structure) is greater than one, the knob is a 
multi-checkbox field. 

kKnobTypeNote The knob value range is equivalent to MIDI keys. 

kKnobTypePan The knob value is the pan setting and is within a range (as 

specified by the low value and high value in the knob 
description structure) that goes from left to right. 

kKnobType Instrument 

The knob value is a reference to another instrument 
number. 

kKnobTypeSetti ng The knob value is one of n different discrete settings — for 
example, items on a pop-up menu. 

kKnobTypeMi 1 1 i seconds 

The knob value is in milliseconds. 

kKnobType Per cent age 

The knob value is a percentage of the range. 

kKnobTypeHertz The knob value represents frequency. 

kKnobTypeButton The knob is a momentary trigger push button. 
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Knob Value Constants 

These constants specify unknown or default knob values and are used in 
various get knob and set knob calls. 

enum { 

l<Unl<nownKnobVal ue = 0x7FFFFFFF, 

l<DefaultKnobValue = 0x7FFFFFFE 

}; 

Constant descriptions 

kUnknownKnobVal ue Couldn't find the specified knob value. 
kDef aul tKnobVal ue Set this knob to its default value. 



Music Packet Status 

These constants are used in the reserved field of the MIDI packet structure 
(page 79). 

enum { 

kMusi c Packet Port Lost 
kMusi c Packet Port Found 
kMusi cPacketTimeGap 

}; 

Constant descriptions 

kMusi c Packet Port Lost 

The application has lost the default input port. 

kMusi cPacketPortFound 

The application has retrieved the input port from the 
previous owner. 

kMusi CPacketTimeGap 

The last byte of the packet specifies how long (in 
milliseconds) to keep the MIDI line silent after sending the 
packet. 



= 1, 
= 2, 

= 3 
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Atomic Instrument Information Flags 

These constants specify what pieces of inforaiation about an atomic instrument 
the caller is interested in and are passed to the Musi cGet Pa rt Atomi c Instrument 
function. 

enum { 

kGetAtomi clnstNoExpandedSampl es = 1 << 0, 

kGetAtomi cInstNoOri gi nal Sampl es =!<<!, 

kGetAtomi clnstNoSampl es = kGetAtomi clnstNoExpandedSampl es | 

kGetAtomi cInstNoOriginalSamples, 

kGetAtomicInstNoKnobList = 1 << 2, 

kGetAtomi clnstNoInstrumentlnfo = 1 << 3, 

kGetAtomi cl nstOri gi nal KnobLi st = 1 << 4, 

kGetAtomi cInstAl 1 Knobs = 1 << 5 

): 

Constant descriptions 

kGetAtomi clnstNoExpandedSampl es 

Eliminate the expanded samples. 

kGetAtomi cInstNoOrigi nal Samples 

Eliminate the original samples. 

kGetAtomi clnstNoSampl es 

Eliminate both the original and expanded samples. 

kGetAtomicInstNoKnobLi st 

Eliminate the knob list. 

kGetAtomi clnstNoInstrumentlnfo 

Eliminate the About box information. 

kGetAtomi cInstOriginal KnobLi st 

Include the original knob list. 

kGetAtomi cInstAl 1 Knobs 

Include the current knob list. 



Flags for Setting Atomic Instruments 

These flags specify details of initializing a part with an atomic instrument and 
are passed to the Mus i cSet Part Atomi cinst rumen t function (page 146). 
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enum ( 

kSetAtomi cInstKeepOri gi nal Instrument = 1 << 0, 

kSetAtomi clnstShareAcrossParts =!<<!, 

l<SetAtomi cInstCal 1 erTosses = 1 << 2, 

l<SetAtomi clnstDontPreprocess = 1 << 7 



Constant descriptions 

l<SetAtonii clnstKeepOriginal Instrument 

Keep original sample after expansion. 

kSetAtomi cInstSha reAcrossPa rts 

Remove the instnmient when the application quits. 

kSetAtomi cInstCal 1 erTosses 

The caller isn't keeping a copy of the atomic instrviment for 
later calls to NASetAtomi cinstrument. 

kSetAtomi clnstDontPreprocess 

Don't expand the sample. You would only set this bit if you 
know the instrument is digitally clean or you got it from a 
Musi cGetPartAtomi cinstrument call (page 146). 



Instrument Info Flags 

Use these flags in the Musi cGetlnstrumentInf o fxmction (page 148) and 
InstrumentGetlnfo function (page 158) to indicate which instruments and 
instrument names you are interested in. 

enum { 

kGetlnstrumentlnfoNoBuiltIn 
kGet Instrument I nf oMi di User Inst 
kGetlnstrumentInf oNoIText 

}; 

Constant descriptions 

kGetlnstrumentInf oNoBui 1 tin 

Don't return built-in instruments. 

kGetlnstrumentInf oMi di User Inst 

Do return user instruments for a MIDI device. 



= 1 << 0, 
=!<<!, 
= 1 << 2 
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kGet Instrument I nfoNoIText 

Don't return international text strings. 



Synthesizer Connection Type Flags 

These flags provide information about a MIDI device's connection and are used 
in the synthesizer connections structure (page 84). 



enum { 

kSyntliesi zerConnecti onMono = 1, 

kSynthesizerConnecti onMMgr = 2, 

kSynthesizerConnecti onOMS = 4, 

kSyntliesi zerConnecti onQT = 8, 

kSyntliesi zerConnecti onFMS = 16 



1; 

Constant descriptions 

kSynthesi zerConnecti onMono 

If set, and the S5mthesizer can be both monophonic and 
pol5^honic, the S5mthesizer is instructed to take up its 
channels sequentially from the system channel in 
monophonic mode. 

kSynthesi zerConnecti onMMgr 

This connection is imported from the MIDI Manager. 

kSynthesi zerConnectlonOMS 

This connection is imported from the Open Music System 
(OMS). 

kSynthesi zerConnecti on QT 

This connection is a QuickTime-only port. 

kSynthesi zerConnecti on FMS 

This connection is imported from the FreeMIDI system. 



Instrument Match Flags 

These flags are returned in the instMatch field of the General MIDI 
instrument information structure (page 81) to specify how QiiickTime 
music architecture matched an instrument request to an instrument. 
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enum { 

l<InstrumentExactMatch = 0x00020000, 

l<InstrumentRecommencleclSubstitute = 0x00010000, 
l<InstrumentQual ityField = OxFFOOOOOO, 

l<Roland8BitQuality = 0x05000000 

}; 

typedef InstrumentAboutlnfo *InstrumentAboutInfoPtr ; 
typedef InstrumentAboutlnfoPtr *InstrumentAboutInfoHandl e; 

Constant descriptions 

l<InstrumentExactMatch 

The instrument exactly matches the request. 

I<lnstrument Recommended Subs ti tute 

The instrument is the approved substitute. 

l<InstrumentQual ityField 

The high-order 8 bits of this field specify the quality of the 
selected instrument. Higher values specify higher quality. 

kRolandSBitQuality 

For built-in instruments, the value of the high-order 8 bits 

is always kInstrumentRol andSBi tQual i ty, which 
corresponds to the quality of an 8-bit Roland instrument. 



Note Request Constants 

These flags specify what to do if the exact instrument requested is not found. 
They are used in the flags field of the note request information structure 
(page 85). 

enum ( 

l<NoteRequestNoGM = 1, 

l<NoteRequestNoSynthType = 2 

}; 

Constant descriptions 

kNoteRequestNoGM Don't use a General MIDI synthesizer. 

kNoteRequestNoSynthType 

Don't use another synthesizer of the same type but with a 
different name. 
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Pick Instrument Flags 

The pick instrument flags provide information to the NAPi cl<Instrument 
(page 120) and NAPi ckEdi tinstrument (page 122) ftinctions on which 
instruments to present for the user to choose from. 



enum { 

kPi ckDontMi x = 1 , 

kPi ckSameSynth = 2, 

kPickUserlnsts =4, 

kPickEditAllowPick = 16 



); 

Constant descriptions 

kPi CkDontMi X Show either all drum kits or all instruments depending on 

the current instrtiment. For example, if it's a drvim kit, 
show only drum kits. 

kPi ckSameSyntli Show only instruments from the current sjmthesizer. 

kPickUserlnsts Show modifiable instruments in addition to ROM 
instruments. 

kPickEditAllowPick 

Present the instrument picker dialog box. Used only with 

the NAPickEditlnstrument ftinction. 

Note Allocator Type 

Use these constants to specify the QuickTime note allocator component. 

enum { 

kNoteAl 1 ocatorType = 'nota' 

kNoteAl 1 ocatorComponentType = 'not2' 

1; 

Constant description 

kNoteAl 1 ocatorType 

The QTMA note allocator type. 

kNoteAl 1 ocatorComponentType 

The QTMA note allocator component type. 
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Tune Queue Depth 

This constant represents the maximum number of segments that can be queued 
with the TuneQueue function (page 91). 

enum { 

l<TuneQueueDepth = 8 

}; 

Constant description 

l<TuneQueueDepth Deepest you can queue tune segments. 

Tune Player Type 

Use this constant to specify the QuickTime time player component. 



enum { 

kTunePl ayerType = 'tune' 

}; 

Constant descriptions 

kTunePlayerType The QuickTime music architecture tune player component 
type. 

Tune Queue Flags 

Use these flags in the TuneQueue function (page 91) to give details about how to 
handle the queued tune. 



enum { 

l<TuneStartNow = 1, 

kTuneDontCl i pNotes = 2, 

kTuneExcl udeEdgeNotes = 4, 

kTuneQui ckStart = 8, 

kTuneLoopUnti 1 = 16, 

kTuneStartNewMaster = 16384 



}; 
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kTuneSta rtNow Play even if another tune is playing. 

kTuneDontCl i pNotes 

Allow notes to finish their durations outside sample. 

kTuneExcludeEdgeNotes 

Don't play notes that start at end of tune. 

kTuneQui ckStart Leave all the controllers where they are and ignore start 
time. 

kTuneLoopUntil Loop a queued time if there is nothing else in the queue. 
kTuneStartNewMaster 

Start a new master reference timer. 

MIDI Component Constants 

Use these constants to specify MIDI components. 

enum { 

kQTMIDIConiponentType= FOUR_CHAR_CODE( 'midi ' ) 

); 

enum { 

kOMSComponentSubType= FOUR_CHAR_CODE( ' OMS '), 

kFMSComponentSubType= FOUR_CHAR_CODE( ' FMS '), 
kMIDIManagerConiponentSubType = FOUR_CHAR_CODE( ' ninigr ' ) 

); 

Constant descriptions 

kQTMIDIComponentType 

The component type for MIDI components. 

kOMSComponentSubType 

The component subtype for a Open Music System MIDI 
component. 

kFMSComponentSubType 

The component subtype for a FreeMIDI component. 

kMIDIManagerConiponentSubType 

The component subtype for a MIDI Manager component. 
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MIDI System Exclusive Constants 

System exclusive constants can be used to control where sample breaks occur 
when importing a MIDI file. For more information, see the section "Importing a 
Standard MIDI File As a Movie Using the Movie Toolbox" (page 34). 

enum { 

kAppl eSysexID = 0x11 , 
kAppl eSysexCmdSampl eSi ze= 0x0001 , 
l<Appl eSysexCmdSampl eBreal<= 0x0002, 
kAppl eSysexCmdAtomi cinstrument = 0x0010, 
kAppl eSysexCmdDevel oper= 0x7F00 

}; 



MIDI File Import Flags 

These flags control the importation of MIDI files. 

enum { 

kMIDI ImportSi 1 enceBefore = 1 << 0, 
kMIDI ImportSi 1 enceAfter = 1 << 1, 
kMIDIImport20Playable = 1 « 2, 
kMIDIImportWantLyrics = 1 << 3 

}; 

Constant descriptions 

kMIDI ImportSi 1 enceBefore 

Specifies to add one second of silence before the first note. 

kMIDI ImportSi 1 enceAfter 

Specifies to add one second of silence after the last note. 

kMIDIImport20Playable 

Specifies to import only MIDI data that can be used with 
QuickTime 2.0. The imported data does not include 
program changes and has at most 32 parts. 

kMI DI ImportWantLy ri cs 

Specifies to import karaoke lyrics as a text track. 
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Part Mixing Flags 

Part mixing flags control how a part is mixed with other parts. 

enum { 

kTuneMi xMute= 1, 
kTuneMixSol 0= 2 

); 

Constant descriptions 

kTuneMi xMute Disables the part so that it is not heard. 

kTuneMi xSol Specifies to include only soloed parts in the mix if any parts 

are soloed. 



Data Structures 



This section describes the data structures provided by QuickTime music 
architecture. 



Instrument Knob Structure 

An instrument knob structure contains information about an instrument knob. 
It is defined by the InstKnobRec data type. 

struct InstKnobRec { 

long number; 
long value; 

1; 

typedef struct InstKnobRec InstKnobRec; 
Field descriptions 

number A knob ID or index. A nonzero value in the high byte 

indicates that it is an ID. The knob index ranges from 1 to 
the number of knobs; the ID is an arbitrary number. 

value The value the knob is set to. 



Data Structures 
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Instrument Knob List 

An instrument knob list contains a list of sound parameters. It is defined by the 

InstKnobLi st data t5^e. 

struct InstKnobList { 

long knobCount; 
long knobFlags; 
InstKnobRec knob[l]; 

}; 

typedef struct InstKnobList InstKnobList; 
Field descriptions 

knobCount The number of instrument knob structures in the list. 

knobFlags Instructions on what to do if a requested knob is not in the 

list. See "Instrument Knob Flags" (page 41). 

k n b [ 1 ] An array of instrument knob structures. 



Atomic Instrument Sample Description Structure 

A sample description structure contains a description of an audio sample, 
including sample rate, loop points, and lowest and highest key to play on. It is 
defined by the InstSampl eDescRec data type. 

struct InstSampl eDescRec ( 



OSType 


dataFormat; 


short 


numChannel s ; 


short 


sampl eSi ze ; 


Unsi gnedPi xed 


sampl eRate ; 


short 


sampl eDatalD; 


1 ong 


offset ; 


1 ong 


numSampl es ; 


1 ong 


1 oopType ; 


1 ong 


1 oopSta rt ; 


1 ong 


1 oopEnd ; 


1 ong 


pi tchNormal ; 


1 ong 


pitchLow; 


1 ong 


pi tchHi gh ; 



1 ; 

typedef struct InstSampl eDescRec InstSampl eDescRec ; 
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Field descriptions 

data Format The data format t5^e. This is either ' twos ' for signed data 

or ' raw ' for unsigned data. 

numChannels The number of channels of data present in the sample. 

sampleSize The size of the sample — 8-bit or 16-bit. 

sampl eRate The rate at which to play the sample in imsigned 

fixed-point 16.16. 

sampleDatalD The ID number of a sample data atom that contains the 

sample audio data. 

offset Set to 0. 

numSampl es The number of data samples in the soimd. 

1 oopType The type of loop. See "Loop Type Constants" (page 41). 

loopStart Indicates the beginning of the portion of the sample that is 

looped if the sound is sustained. The position is given in 
the number of data samples from the start of the soimd. 

1 OOP End Indicates the end of the portion of the sample that is looped 

if the soimd is sustained. The position is given in the 
number of data samples from the start of the sound. 

pitcliNormal The nirmber of the MIDI note produced if the sample is 

played at the rate specified in sampl eRate. 

pi tciiLow The lowest pitch at which to play the sample. Use for 

instruments, such as pianos, that have different samples to 
use for different pitch ranges. 

p i t cli H i g Pi The highest pitch at which to play the sample. Use for 

instrtiments, such as pianos, that have different samples to 
use for different pitch ranges. 



Synthesizer Description Structure 

A synthesizer description structure contains information about a synthesizer. It 
is defined by the SynthesizerDescription datatype. 

struct SynthesizerDescription { 

OSType syntliesi zerType ; 

Str31 name; 
unsigned long flags; 
unsigned long voiceCount; 
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unsi 


gned 


1 ong 


partCount; 


unsi 


gned 


1 ong 


i nstrumentCount ; 


unsi 


gned 


1 ong 


modi f i abl el nstrumentCount ; 


unsi 


gned 


1 ong 


channelMasl<; 


unsi 


gned 


1 ong 


drumPartCount; 


unsi 


gned 


1 ong 


drumCount ; 


unsi 


gned 


1 ong 


modi f i abl eDrumCount ; 


unsi 


gned 


1 ong 


drumChannelMasl<; 


unsi 


gned 


1 ong 


outputCount ; 


unsi 


gned 


1 ong 


1 atency ; 


unsi 


gned 


1 ong 


control 1 ers [4] ; 


unsi 


gned 


1 ong 


gmlnstruments[4] ; 


unsi 


gned 


1 ong 


gmDrums [4] ; 



}; 

typedef struct Synthesi zerDescri pti on Synthesi zerDescri pti on ; 



Field descriptions 

synthesi zerType The S3mthesizer t3^e. This is the same as the music 
component subtype. 

name Text name of the synthesizer type. 

flags Various information about how the synthesizer works. See 

"Synthesizer Description Flags" (page 42). 

voiceCount Maximum polyphony. 

partCount Maximum multi-timbrality (and MIDI channels) . 

i nstrumentCount The number of built-in ROM instruments. This does not 
include General MIDI instruments. 

modi f i abl el nstrumentCount 

The number of slots available for saving user-modified 
instruments. 

channelMasl< Which channels a MIDI device always uses for 

instruments. Set to FFFF for all channels. 

drumPartCount The maximum multi-timbrality of drum parts. For 
synthesizers where dnrni kits are separated from 
instnraients . 

drumCount The number of built-in ROM drtim kits. This does not 

include General MIDI drum kits. For synthesizers where 
drum kits are separated from instruments 
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modifiableDrumCount 

The number of slots available for saving user-modified 
drum kits. For MIDI synthesizers where drum kits are 
separated from instruments 

drumCliannel Mask Which channels a MIDI device always uses for drum kits. 
Set to FFFF for all channels 

outputCount The number of audio outputs . This is usually two. 

latency Response time in microseconds. 

control 1 ers [4] An array of 128 bits identifying the available controllers. 

See "Controller Numbers" (page 56). Bits are numbered 
from 1 to 128, starting with the most significant bit of the 
long word, and continuing to the least significant of the last 
bit. 

gmlnstruments [4] An array of 128 bits giving the available General MIDI 
instruments. 

gniDrunis[4] An array of 128 bits giving the available General MIDI 

drum kits. 



Tone Description Structure 



A tone description structure provides the information needed to produce a 
specific musical soimd. The tune header has a tone description for each 
instrument used. Tone descriptions are also used in the tone description atoms 
of atomic instrimients. The tone description structure is defined by the 
ToneDescri pti on data type. 

struct ToneDescri pti on { 

Bi gEndi anOSType synthesi zerType ; 

Str31 synthesi zerName ; 

Str31 i nstrumentName ; 

Bi gEndi an Long i nst rumen t Number ; 

Bi gEndi anLong gmNumber; 

); 

typedef struct ToneDescri pti on ToneDescri pti on ; 
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Field descriptions 

synthesi zerType The synthesizer t5^e. See "Synthesizer Type Constants" 

(page 42) for possible types. A value of specifies that any 
type of synthesizer is acceptable. 

synthesi zerName The name of the synthesizer component instance. A value 
of specifies that the name can be ignored. 

i nstrumentName The name of the instrument to use. 

i nstrumentNumber The instrument number of the instrument to use. This 
value, which must be in the range 1-262143, can specify 
General MIDI and GS instruments as well as other 
instruments (see Table 2-2). The instrument specified by 
this field is used if it is available; if not, the instrument 
specified by the gmNumber field is used. If neither of the 
instruments specified by the i nstrumentNumber or gmNumber 
fields is available, the instrument specified by the 
i nstrumentName field is used. Finally, if none of these fields 
specifies an instrument that is available, no tone is played. 

gmN umbe r The instrtiment ntimber of a General MIDI or GS 

instrument to use if the instrirment specified by the 
i nstrumentNumber field is not available. This value, which 
must be in the range 1-16383, can specify only General 
MIDI and GS instruments (see Table 2-2). The instrument 
specified by the i nstrumentNumber field is used if it is 
available; if not, the instrument specified by the gmNumber 
field is used. If neither of the instruments specified by the 
i nstrumentNumber or gmNumber fields is available, the 
instrviment specified by the i nstrumentName field is used. 
Finally, if none of these fields specifies an instrument that is 
available, no tone is played. 

GS instruments conform to extensions defined by Roland Corporation to the 
General MIDI specifications. For information about these extensions, see 

http : //www. rolandcorp.com/vsc/gsl. html 
on the World Wide Web. 
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Table 2-1 



Name 


Low 


Hiah 


Low (Hex) 


High (Hex) 


GM Instrument 


1 


1 28 


0x00000001 


0x00000080 


GIVI Drumkit 


16385 


16512 


0x00004001 


0x00004080 


GS Instrument 


128 


16383 


0x00000081 


0X00003FFF 


ROM Instrument 


32768 


65535 


0x00008000 


OxOOOOFFFF 


User Instrument 


65536 


131071 


0x00010000 


0x0001 FFFF 


Internal Index 


131072 


262143 


0x00020000 


0X0003FFFF 


All Other Numbers Illegal And Reserved 



Table 2-2 



I Range descriptions 



GM instrument 



GM drum kit 



GS instrument 



ROM instrument 



User instrument 



Internal index 



An instrument number in this range specifies a standard 
General MIDI instrument that should soimd the same on 
all synthesizers that support General MIDI. 

An instrirment number in this range specifies a standard 
General MIDI drum kit instrument that should sound the 
same on all synthesizers that support General MIDI. 

An instrument number in this range specifies a standard 
GS instrument that should sound the same on all 
synthesizers that support the Roland GS extensions to 
General MIDI. 

An instrument number in this range specifies an 
instrument of a synthesizer that not a standard General 
MIDI or GS instrument. 

Instruments number in this range are transient and are 
assigned when necessary for additional instruments, such 
as instrviments in a newly installed GS library or custom 
instruments for a game. Applications should refer to these 
additional instruments by name rather by number. 

An instrument index value returned by the MusicFindTone 

function that can be passed immediately in a call to 

Musi cSet Part Instrument Number. Values in this range are not 
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persistent and should never be stored or used in any other 
way. 



Knob Description Structure 



A knob description structure contains sound parameter values for a single 
knob. It is defined by the KnobDescri pti on data type. 

struct KnobDescri pti on { 

Str63 name; 
long lowValue; 
long highValue; 
long def aul tVal ue ; 

1 ong flags; 
long knobID; 

}; 

typedef struct KnobDescri pti on KnobDescri pti on ; 
Field descriptions 

name The name of the knob. 

1 owVa 1 ue The lowest number you can set the knob to. 

highValue The highest number you can set the knob to. 

defaultValue A value to use for the default. 

f 1 ags Various information about the knob. See "Knob Flags" 

(page 60). 

!< n b I D A knob ID or index. A nonzero value in the high byte 

indicates that it is an ID. The knob index ranges from 1 to 
the nimiber of knobs; the ID is an arbitrary number. Use the 
knob ID to refer to the knob in preference to the knob 
index, which may change. 



Instrument About Information 

The instrument About information structure contains the information that 
appears in the instrument's About box and is returned by the 
Musi cGetlnstrumentAboutlnfo function (page 148). It is defined by the 
InstrumentAboutlnfo data tj^e. 
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struct InstrumentAboutlnfo { 

PicHandle p; 
Str255 autlior; 
Str255 copyriglit; 
Str255 otiier; 

); 

typedef struct InstrumentAboutlnfo InstrumentAboutlnfo; 
Field descriptions 

p A handle to a graphic for the About box. 

a u t In r The author 's name. 

copy ri gilt The copyright information. 

1 Pi e r Any other textual information. 



MIDI Packet 

The MIDI packet structure describes the data passed by note allocation calls. It 
is defined by the Musi cMIDIPacket datatype. 

struct MusicMIDIPacket { 

unsigned sliort length; 
unsigned long reserved; 
UlntS data[249]; 

1; 

typedef struct MusicMIDIPacket MusicMIDIPacket; 
Fieid descriptions 

1 e n g t li The length of the data in the packet. 

reserved This field contains zero or one of the music packet status 

constants. See "Music Packet Status" (page 62). 

data [249] The MIDI data. 

Note 

This is the count of data bytes only, unlike MIDI Manager 
or OMS packets. 
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Instrument Information Structure 



The instrument information structure provides identifiers for instriiments and 
is part of the instrument information list. It is defined by the 

InstrumentlnfoRecord data type. 

struct InstrumentlnfoRecord { 

long i nstrumentNumber ; 

long flags; 
long toneNamelndex; 
long itxtNameAtomlD; 

}; 

typedef struct InstrumentlnfoRecord InstrumentlnfoRecord; 
Field descriptions 

i nstrumentNumber The instrument number. If the number is 0, the name is an 
instrument category. See Table 2-2 (page 77) for the ranges 
of instrument numbers. If the value of the instrument 
number is greater than 65536, its value is transient, and the 
instrument should be identified by name rather than by 
number except when the value is immediately passed to 
the Musi cSetPartlnstrumentNumber function. 

flags Unused. Must be 

toneNamelndex The instrument's position in the toneNames index stored in 
the instrument information list this structure is a part of. 
The index is a one-based index. 

i txtNameAtomI D The instrument's position in the i txtNames index stored in 
the instrument information list this structure is a part of. 



Instrument Information List 

An instrument information list contains the list of instruments available on a 
synthesizer. It is defined by the InstrumentlnfoLi st data type. 

struct InstrumentlnfoLi st { 

long recordCount; 
Handle toneNames; 
QTAtomContai ner itxtNames; 
InstrumentlnfoRecord info[l]; 



80 



Data Structures 



CHAPTER 2 

Music Architecture Reference 



typedef struct InstrumentlnfoLi st InstrumentlnfoLi st ; 
typedef InstrumentlnfoLi st *InstrumentInfoLi stPtr ; 
typedef InstrumentlnfoLi stPtr *InstrumentInfoLi stHandl e ; 

Field descriptions 

recordCount The number of structures in the list. 

toneNames A string list of the instrument names as specified in their 

tone descriptions. 

i txtNames A list of international text names, taken from the name 

atoms. 

i n f [ 1 ] An array of instrument information structures. 



General MIDI Instrument Information Structure 

The General MIDI instrument information structure provides information about 
a General MIDI instrument within an instrument component. It is defined by 
the GMInstrumentInf data type. 

struct GMInstrumentlnfo { 

long cmpInstID; 
long gmlnstNum; 
long instMatcli; 

1; 

typedef struct GMInstrumentlnfo GMInstrumentlnfo; 
typedef GMInstrumentlnfo *GMInstrumentInfoPtr ; 
typedef GMInstrumentlnfoPtr *GMInstrumentInfoHandl e ; 

Field descriptions 

cmpInstID 

gml nstNum 
instMatch 



The number of the instnmient within the instnmient 
component. 

The General MIDI, or standard, instrument number. 

A flag indicating how the instnmient matches the 
requested instrument. See "Instrument Match Flags" 
(page 65). 
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Non-General MIDI Instrument Information Structure 

The non-General MIDI information stiructiire provides information about 
non-General MIDI instruments within an instrument component. It is defined 

by the nonGMInstrumentInf oRecord data type. 

struct nonGMInstrumentlnfoRecord { 

long cmpInstID; 
long flags; 
long toneNamelndex; 
long itxtNameAtomlD; 

}; 

typedef struct nonGMInstrumentlnfoRecord nonGMInstrumentlnfoRecord; 
Field descriptions 

cmp I n s 1 1 D The number of the instrument within the instrument 

component. If the ID is 0, the name is a category name. 

flags Not used. 

toneNamelndex The instrument's position in the toneNames index stored in 
the instrument information list this structure is a part of. 
The index is a one-based index. 

itxtNameAtomlD The instrument's position in the itxtNaines index stored in 
the instrimient information list this structure is a part of. 



Non-General MIDI Instrument Information List 



A non-General MIDI instrument information list contains the list of 
non-General MIDI institiments supported by an instrument component. It is 
defined by the nonGMInstrumentlnfo data t5^e. 

struct nonGMInstrumentlnfo { 

long recordCount; 

Handle toneNames; 

QTAtomContai ner itxtNames; 

nonGMInstrumentlnfoRecord instInfo[l]; 

typedef struct nonGMInstrumentlnfo nonGMInstrumentlnfo; 
typedef nonGMInstrumentlnfo *nonGMInstrumentInfoPtr; 
typedef nonGMInstrumentlnfoPtr *nonGMInstrumentInfoHandl e; 
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Field descriptions 

recordCount Niimber of structures in the list. 

toneNames A short string Hst of the instrument names as specified in 

their tone descriptions. 

itxtNames A list of international text names, taken from the name 

atoms. 

i n s 1 1 n f [ 1 ] An array of non-General MIDI instrument information 

structures. 



Complete Instrument Information List 



The complete instrument information list contains a list of all atomic 
instruments supported by an instrument component. It is defined by the 

InstConipInf data t5^e. 

struct InstCompInf { 

long infoSize; 

long GMi nstrumentCount ; 

GMInstrumentlnfoHandl e GMi ns t rumen t Info ; 

long GMdrumCount ; 

GMInstrumentlnfoHandl e GMdrumlnfo ; 

long nonGMi nstrumentCount ; 

nonGM Instrument I nfoHandl e nonGMi nstrumentlnfo ; 

long nonGMdrumCount ; 

nonGM Instrument I nfoHandl e nonGMdrumInf o ; 

1; 

typedef struct InstCompInfo InstCompInf o ; 
typedef InstCompInfo *InstCompInf oPtr ; 
typedef InstCompInf oPtr *InstCompInf oHandl e ; 

Field descriptions 

InfoSize The size of this structure in bytes. 

GMi nstrumentCount The number of General MIDI instruments. 

GMi nstrumentlnfo A handle to a list of General MIDI instrument information 
structures. 

GMdrumCount The number of General MIDI drum kits . 

GMdrumlnfo A handle to a list of General MIDI instrument information 

structures. 
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nonGMi nst rumen tCount 

The number of non-General MIDI instruments. 

nonGMi nst rument Info 

A handle to the list of non-General MIDI instruments. 

nonGMd rumCount The number of non-General MIDI drum kits. 

nonGMdrumI nf A handle to the list of non-General MIDI drum kits. 



Synthesizer Connections for MIDI Devices 



The S5mthesizer connection structure describes how a MIDI device is connected 
to the computer. It is defined by the Synthesi zerConnecti ons data type. 

struct Synthesi zerConnecti ons { 

OSType clientID; 
OSType inputPortlD; 
OSType outputPortID; 
1 ong mi di Channel ; 

long flags; 
long unique; 
long reservedl; 
long reserved?; 

}; 

typedef struct Synthesi zerConnecti ons Synthesi zerConnecti ons ; 
Field descriptions 

clientID The client ID provided by the MIDI Manager or ' QMS ' for 

an OMS port. 

inputPortID The ID provided by the MIDI Manager or OMS for the port 

used to send to the MIDI synthesizer. 

outputPortID The ID provided by the MIDI Manager or OMS for the port 

that receives from a keyboard or other control device. 

m i d i C h a n n e 1 The system MIDI channel or, for a hardware device, the slot 

number. 

flags Information about the t5^e of connection. See "Synthesizer 

Connection Type Flags" (page 65). 

unique A unique ID you can use instead of an index to identify the 

synthesizer to the note allocator. 
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reservedl Reserved. Set to 0. 

reserved? Reserved. Set to 0. 

QuickTime MIDI Port 

This structure provides information about a MIDI port. 

struct QTMIDIPort { 

SynthesizerConnections portConnections; 
Str63 portName; 

): 

typedef struct QTMIDIPort QTMIDIPort; 
Field descriptions 

portConnections A synthesizer connections structure (page 84). 
portName The name of the output port. 

QuickTime MIDI Port List 

This structure contains a list of QuickTime MIDI port structures. 

struct QTMIDIPortList { 

short portCount; 
QTMIDIPort port[l]; 

1; 

typedef struct QTMIDIPortList QTMIDIPortList; 
Field descriptions 

portCount The number of MIDI ports in the list. 

port An array of QuickTime MIDI port structures. 

Note Request Information Structure 

The note request information structure contains information for allocating a 
note channel that's in addition to that included in a tone description structure. It 
is defined by the NoteRequestlnfo datatype. 
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struct NoteRequestlnfo { 

UInt8 flags; 
UlntS reserved; 
short polyphony; 
Fixed typi cal Polyphony ; 

}; 

typedef struct NoteRequestlnfo NoteRequestlnfo; 
Field descriptions 

flags Specifies what to do if the exact instrument requested in a 

tone description structure is not found. See "Note Request 
Constants" (page 66). 

reserved Reserved. Set to 0. 

polyphony Maximum ntimber of voices . 

typical Polyphony Hint for level mixing. 



Note Request Structure 

A note request structure combines a tone description structure and a note 
request information structure to provide all the information available for 
allocating a note channel. It is defined by the NoteRequest data type. 

struct NoteRequest { 

NoteRequestlnfo info; 
ToneDescri pti on tone; 

}; 

typedef struct NoteRequest NoteRequest; 
Fieid descriptions 

info A note request information structure (page 85). 

tone A tone description structure (page 75). 



Tune Status 

The time status structure provides information on the currently playing tune. 
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struct TuneStatus { 

unsigned long tune; 
unsigned long tunePtr; 
TimeValue time; 
sliort queueCount; 
sliort queueSpots; 
TimeValue queueTime; 
long reserved[3]; 

); 

typedef struct TuneStatus TuneStatus; 
Field descriptions 

tune The currently playing tune. 

t u n e P t r Current position within the playing tone. 

time Current tune time. 

queueCount Number of tunes queued up. 

queueSpots Number of tunes that can be added to the queue. 

queueTi me Total amoimt of playing time represented by times in the 
queue. This value can be very inaccurate. 

reserved[3] Reserved. Set to 0. 



Functions 



The functions provided by the note allocator component, the tune player 
component, music components, and instrument components are described in 
the following sections. 



Tune Player Functions 

This section describes the functions the time player provides for setting, 
queueing, and manipulating music sequences. It also describes tune player 
utility fimctions. 
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TuneSetHeader 



The TuneSetHeader function prepares the tune player to accept subsequent 
music event sequences by defining one or more parts to be used by sequence 
Note events. 

pascal ComponentResul t TuneSetHeader( 
TunePlayer tp, 
unsigned long *header); 

tp A tune player identifier, obtained from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

header A pointer to a list of instruments that will be used in subsequent 

calls to the TuneQueue function. The list can include note request 
General events with subt5^es of kGeneral EventNoteRequest, 
i<General Event Part Key, kGeneral Event At omi c Instrument, 
kGeneral EventMIDIChannel, and kGeneral EventUsedNotes. It can 
also include atomic instruments. The list is terminated by a 
marker event of subtype end. 

function result A result code. 



DISCUSSION 

The TuneSetHeader function is the first QuickTime music architecture call to play 
a music sequence. The header parameter points to one or more initialized 
General events and atomic instruments. The event list pointed to by the header 
parameter must conclude with a marker event of subtype end. 

Only one call to TuneSetHeader is required. Each TuneSetHeader call resets the 
time player. 

SEE ALSO 

The TuneSetHeaderWi thSize function (page 89) and the TuneSetNoteChannel s 
fimction (page 89). 
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TuneSetHeaderWithSize 



The TuneSetHeaderWi tInSize function is like the TuneSetHeader function in that it 
prepares the tune player to accept subsequent music event sequences by 
defining one or more parts to be used by sequence Note events. But unlike the 
TuneSetHeader fimction, TuneSetHeaderWi thSi ze allows you to specify the header 
length in bytes. This prevents the call from parsing off the end if the music 
event sequence is missing an end marker. 

extern pascal ComponentResul t TuneSetHeaderWitliSizeC 
TunePlayer tp, 
unsigned long *lieader, 
unsi gned 1 ong size); 

tp A tune player identifier, obtained from the Component 

Manager's OpenComponent fimction. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

Pi e a d e r A pointer to a list of instruments that wiU be used in subsequent 

calls to the luneQueue function. The list can include General 
events with subtypes of kGeneral EventNoteRequest, 
kGeneral Event Part Key, kGeneral Event At omi cinstrument, 
kGeneral EventMIDIChannel, and kGeneral EventUsedNotes. It can 
also include atomic instruments. The list is terminated by a 
marker event of subt5^e end. 

size The size of the header in bytes. 



SEE ALSO 



The TuneSetHeader function (page 88) and the TuneSetNoteCliannel s 
function (page 89). 
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TuneSetNoteChannels 



You use the TuneSetNoteChannel s function to assign note channels to a tune 
player. 

extern pascal ComponentResul t TuneSetNoteChannel s ( 
TunePlayer tp, 
unsigned long count, 
NoteChannel *noteChannel Li st , 
TunePl ayCal 1 Bacl<UPP pi ayCal 1 Bacl<Proc, 
1 ong ref Con ) ; 

tp Specifies the instance of a tune player component for this 

operation. Your software obtains this reference when calling the 
Component Manager's OpenComponen L or OpenDef aul tComponent 
fimction. See the chapter "Component Manager" in QuickTime 3 
Reference for details. 

count The number of note channels to assign. 

noteChannel Li st 

A pointer to the list of note channels to assign. 

pi ayCal 1 BackProc 

A pointer to a function in youj software that is called for each 
event whose part number is greater than the value of the count 
parameter. 

r e f C n A reference constant that is passed to the function specified by 

the pi ayCall BackProc parameter whenever it is called. 

DISCUSSION 

When you call TuneSetNoteChannels, any note channels that were previously 
assigned to the tune player are no longer used and are disposed of. 

The parts for the note channels you assign are numbered from 1 to the value of 
the count parameter. 

The pi ayCal 1 BackProc and ref Con parameters let you to use the tune player as a 
general purpose timer/ sequencer. The fimction in your software pointed to by 
the pi ayCall BackProc parameter is called for each event whose part number is 
greater than the value of the count parameter. Events whose part numbers are 



90 



Functions 



CHAPTER 2 

Music Architecture Reference 



less than or equal to the value of the count parameter are passed to the note 
channel rather than the callback procedure. 

The playCallBacl<Proc parameter must point to a function with the following 
prototype: 

typedef pascal void (*TunePl ayCal 1 BackProcPtr ) ( 
unsigned long *event, 
long seed, 
1 ong ref Con ) ; 

The event parameter is a pointer to a QuickTime music event structure in the 
sequence data. The seed parameter is a 32-bit value that is guaranteed to be 
different for each call to the callback routine (unless 2 ''3 2 calls are made, after 
which the values repeat), with one exception: the value passed at the beginning 
of a note is also passed at the end of the note's duration, together with a note 
structure or an extended note in which the velocity bits are set to 0. The ref Con 
parameter is the reference constant that is passed to the TuneSetNoteChannels 
function. 



TuneQueue 



The TuneQueue function places a sequence of music events into a queue to be 
played. 

pascal ComponentResul t TuneQueueC 

TunePlayer tp, 
unsigned long *tune. 
Fixed tuneRate, 

unsigned long tuneStartPosition, 
unsigned long tuneStopPosition, 
unsigned long queueFlags, 
TuneCal 1 BackUPP cal 1 BackProc , 
1 ong ref Con ) ; 

tp A tune player identifier, obtained from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 
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tune Pointer to an array of events, terminated by a marker event of 

subtype end. 

tuneRate Fixed-point speed at which to play the sequence. "Normal" 
speed is 0x00010000. 

tuneStartPosi ti on 

Sequence starting time. 

tuneStopPosi ti on 

Sequence ending time. 

queueFlags Flags with details about how to play the queued tunes. For valid 
values see "Tune Queue Flags" (page 68). 

callBacl<Proc Points to your callback function. Your callback fimction must 
have the following form: 

pascal void MyCal 1 BackProc 
(QTCallBacl< cb, long refcon); 

r e f c n Contains a reference constant value. The Movie Toolbox passes 

this reference constant to your error-notification function each 
time it calls your function. 

function result A result code. In addition to QuickTime music architecture 
result codes, this function may return Ti me Base result codes. 



DISCUSSION 

The tuneStartPosltlon and tuneStopPosi ti on parameters specify, in time units 
ntimbered from zero for the beginning of the sequence, which part of the 
queued sequence to play. To play all of it, pass and OxFFFFFFFF, respectively. 

If there is a sequence currently playing, the newly queued sequence begins as 
soon as the active sequence ends unless the queueFlags parameter is 
i<TuneSta rtNow, in which case the currently playing sequence is immediately 
terminated and the new one started. 
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Tune Stop 

The TuneStop function stops a currently playing sequence. 

pascal ConiponentResul t TuneStop( 

TunePlayer tp, 
1 ong stopFl ags ) ; 

tp A tune player identifier, obtained from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

stopFlags Must be zero. 

function result A result code. 



TuneGetVolume 



The TuneGetVol ume function returns the voliraie associated with the entire 
sequence. 

pascal ConiponentResul t TuneGetVol ume( 
TunePl ayer tp) ; 

tp A time player identifier, obtained from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

function result The volume as a value from 0.0 to 1.0 or a negative result code. 



TuneSetVolume 



The TuneSetVol ume fimction sets the volume for the entire sequence. 

pascal ComponentResul t TuneSetVol ume( 
TunePlayer tp, 
Fixed vol ume) ; 
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tp A tune player identifier, obtained from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

vol ume The volume to use for the sequence. The value is a fixed 16.16 

number. 

function result A result code. 



DISCUSSION 

The TuneSetVolume function sets the volume level of the active sequence to the 
value of the vol ume parameter ranging from 0.0 to 1.0. 

Note 

Individual instruments within the sequence can maintain 
independent volume levels. ♦ 



TuneSetSoundLocalization 



The TuneSetSoundLocal i zati on function passes sound localization data to a tune 
player. 

extern pascal ComponentResul t TuneSetSoundLocal i zati on ( 
TunePlayer tp, 
Handle data ) ; 

tp A time player identifier, obtained from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

data The soimd localization data to be passed. 

function result A result code. 
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TuneGetTimeBase 



The TuneGetTimeBase function returns the time base of the tune player. 

pascal ConiponentResul t TuneGetTinieBase( 
TunePlayer tp, 
TimeBase *tb) ; 

tp A tune player identifier, obtained from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

t b An initialized T i me B a s e object. 

function result A result code. 



DISCUSSION 

The TuneGetTimeBase fimction returns, in the tb parameter, the time base used to 
control the sequence timing. The sequence can be controlled in several ways 
through its time base. The rate of playback can be changed, or the Ti meBase 
object can be slaved to a clock or time base different than real time. 



TuneGetTimeScale 



The TuneGetTimeScale function returns the current time scale, in 
imits-per-second, for the specified time player instance. 

pascal ConiponentResul t TuneGetTimeScal e( 
TunePlayer tp, 
TimeScale *scale) ; 

tp A tune player identifier, obtained from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

scale An initialized TimeScale object. 

function result A result code. 
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TuneSetTimeScale 



The TuneSetTimeScale function sets the time scale used by the specified tune 
player instance. 

pascal ComponentResul t TuneSetTimeScal e( 

TunePlayer tp, 
TimeScal e seal e) ; 



tp A tune player identifier, obtained from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

scale The time scale value to be used, in units per second. 

function result A resiilt code. 



DISCUSSION 

The TuneSetTimeScal e function sets the time scale data used by the tune player's 
sequence data when interpreting time-based events. 



TuneGetPartMix 



You use the TuneGetPartMix function to get volume, balance, and mixing 
settings for a specified part of a time. 

pascal ComponentResul t TuneGetPartMix ( 
TunePlayer tp, 
unsigned long partNumber, 
long *volumeOut, 
long *balanceOut, 
1 ong *mixFl agsOut) ; 



tp Specifies the instance of a tune player component for this 

request. Your software obtains this reference when calling the 
Component Manager's OpenComponent or OpenDefaul tComponent 
function. 

pa rtNumber Specifies the part number for this request. 
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vol umeOut Returns the volume for the part. 
balanceOut Returns the balance for the part. 

mixFlagsOut Returns flags that control part mixing. These flags are described 
in "Part Mixing Flags" (page 71). 



TuneSetPartMix 



You use the TuneSetPartMix function to set volume, balance, and mixing 
settings for a specified part of a tune. 

pascal ComponentResul t TuneSetPartMix ( 
TunePlayer tp, 
unsigned long partNumber, 
long volume, 
long balance, 
1 ong mi xFl ags ) ; 

Specifies the instance of a time player component for this 
request. Your software obtains this reference when calling the 
Component Manager's OpenComponent or OpenDef aul tComponent 
function. 

Specifies the part number for this request. 
Specifies the voliime for the part. 
Specifies the balance for the part. 

Flags that control part mixing. These flags are described in "Part 
Mixing Flags" (page 71). 



tp 

partNumber 
vol ume 
bal ance 
mixFl ags 
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Tunelnstant 



You can use the Tunelnstant function to play the particular sequence events 
active at a specified position. 

pascal ComponentResul t Tunelnstant( 
TunePlayer tp, 
unsigned long *tune, 
unsigned long tunePosi ti on ) ; 



tp A tune player identifier, obtained from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

tune Pointer to tune sequence data. 

tunePosi ti on Position within time sequence data in time linits. 

function result A result code. 



DISCUSSION 

The Tunelnstant fimction plays the notes that are "on" at the point specified by 
the tunePosi ti on parameter. The notes are started and then left playing on 
return. The notes can be silenced by calling the TuneStop function. This call is 
useful for enabling user "scrubbing" on a sequence. 



TunePreroU 



The TunePreroll function prepares for playing tune player sequence data by 
attempting to reserve note channels for each part in the sequence. 

pascal ComponentResul t TunePreroll (TunePlayer tp); 

tp A tune player identifier, obtained from the Component 

Manager's OpenComponent ftinction. See the chapter "Component 
Manager" for details. 

function result A result code. 
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TuneUnroU 



The TuneUnroll function releases any note channel resources that may have 
been locked down by previous calls to T u n e P r e r o 1 1 for this tune player. 

pascal ComponentResul t TuneUnroll (TunePlayer tp); 

tp A time player identifier, obtained from the Component 

Manager's OpenCoinponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

function result A result code. 



TuneGetlndexedNoteChannel 



You can use the TuneGetlndexedNoteChannel function to determine how many 
parts the time is playing and which instrimaent is assigned to those parts. 

pascal ComponentResul t TuneGetlndexedNoteCliannel ( 
TunePlayer tp, 
1 ong i , 

NoteCliannel *nc); 

tp A ttme player identifier, obtained from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" for details. 

i Note channel index or to get the nimiber of parts. 

n c Allocated initialized note channel. 

function result A positive value is the nimiber of note channels used by the 
tune player; a negative value is a result code. 

DISCUSSION 

The tune player allocates note channels that best satisfy the requested 
instrument in the tune header. The application can use this call to determine 
which instrument was actually used for each note channel. The 
TuneGetlndexedNoteCliannel function takes the tune player in the tp parameter 
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and returns the number of parts (l...n) allocated to the tune player. You can then 
pass the function a part index and it returns, in the nc parameter, the note 
channel allocated for that part. 



TuneGetStatus 



The TuneGetStatus function returns an initialized structure describing the state 
of the time player instance. 

pascal ComponentResul t TuneGetStatus ( 
TunePlayer tp, 
TuneStatus *status); 

tp A tune player identifier, obtained from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

status A pointer to an initialized tune status structure (page 86). 

function result A resiilt code. 



TuneSetPartTranspose 



The TuneSetPartTranspose function modifies the pitch and volume of every note 
of a tune. 

extern pascal ComponentResul t TuneSetPartTranspose( 
TunePlayer tp, 
unsigned long part, 
long transpose, 
long vel oci tyShi ft ) ; 

tp A tune player identifier, obtained from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" for details. 

part The part for which you want to change pitch and volume. 
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transpose A value by which to modify the pitch of the note. The value is a 
small integer for semitones or an 8.8 fixed-point number for 
microtones. 

vel OCT tySlii ft 

A value to add to the vel oci ty parameter passed to the 
NAPl ayNote function. 

function result A result code. 



TuneGetNoteAllocator 



The TuneGetNoteAllocator function returns the instance of the note allocator 
that the tune player is using. 

extern pascal NoteAnocator TuneGetNoteAll ocator (TunePlayer tp); 

tp A time player identifier, obtained from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 



function result A note allocator or a result code. 



TuneSetSofter 



The TuneSetSofter fimction adjusts the volirme a tune is played at to the softer 
volume produced by QuickTime 2.1. Files imported with QuickTime 2.1 
automatically played softer. Files imported with QuickTime 2.5 or later play at 
the new, louder volirme. 

extern pascal ConiponentResul t TuneSetSofter( 
TunePlayer tp, 
1 ong softer ) ; 

tp A time player identifier, obtained from the Component 

Manager's OpenComponent fimction. See the chapter "Component 
Manager" for details. 
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softer A value of 1 means play at the QuickTime 2.1 volume; a value of 

means don't make the volume softer. 

function result A result code. 



TuneSetBalance 



Use the TuneSetBalance function to modify the pan controller setting for a tune 
player. 

extern pascal ComponentResul t TuneSetBal ance( 
TunePlayer tp, 
long balance); 

tp A tune player identifier, obtained from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

balance Modifies the pan controller setting. Valid values are from -128 to 

128 for left to right balance. 

function result A result code. 



TuneTask 



Call the TuneTask function periodically to allow a time player to perform tasks it 
must perform at foreground task time. 

extern pascal ComponentResul t TuneTasl< (TunePlayer tp); 

tp A time player identifier, obtained from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

function result A result code. 
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DISCUSSION 

Certain operations can be performed only at foregroiind application task time. 
Specifically, the QuickTime music synthesizer cannot load instruments from 
disk at interrupt time. As a result, embedded program changes are not 
performed imtil TuneTaskis called. 



Note Allocator Functions: Note Channel Allocation and Use 

The ftinctions described in this section create, manipiilate, and get information 
about note channels. 



NANewNoteChannel 



The NANewNoteClnannel function requests a new note channel with the qualities 
described in the noteRequest structure. 

pascal ComponentResul t NANewNoteChannel ( 
NoteAl 1 ocator na, 
NoteRequest *noteRequest , 
NoteChannel *outChannel ) ; 



na You obtain the note allocator identifier from the Component 

Manager's OpenComponent fimction. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

noteRequest Apointer to a note request structure. 

outCliannel On exit, a pointer to an identifier for a new note channel or n i 1 if 
the function fails to create a note channel. 

function result A result code. 



DISCUSSION 

The caller can request an instriiment that is not ciirrently allocated to a part. In 
that case, the NANewNoteChannel fimction may return a value in outChannel, even 
though the request cannot initially be satisfied. The note channel may become 
valid at a later time, as other note channels are released or other music 
components are registered. 
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The NANewNoteChannel function searches all available music components for the 
instrument that best matches the specifications in the ToneDescri pi on structure 
that is contained within the noteRequest parameter. 

If an error occurs, the note noteChannel is initialized to ni 1 . 



NANewNoteChannelFromAtomicInstrument 



You can use the NANewNoteChannel FromAtomic Instrument function to request a 
new note channel for an atomic instrument. 

extern pascal ComponentResul t NANewNoteChannel FromAtomi clnstrument( 
NoteAl 1 ocator na, 
Atomi cInstrumentPtr i nstrument , 
long flags, 

NoteChannel *outChannel ) ; 

na You obtain the note allocator identifier from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

i nstrument A pointer to the atomic instrument. This may be a dereferenced 
locked QT atom container. 

flags These flags specify details of initializing a part with an atomic 

instrument. See "Flags for Setting Atomic Instruments" 
(page 63). 

outChannel On exit, a pointer to an identifier for a new note channel or n i 1 
if the function fails to create a note channel. 

function result A result code. 



DISCUSSION 

The NANewNoteChannel FromAtomi cinstrument function takes a note allocator 
identifier in the n a parameter and a pointer to the atomic instrument you are 
requesting a new charmel for in the i nstrument parameter. Among other things, 
you can specify how to handle the expanded sample with the flags parameter. 
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The function returns the note channel allocated for the instrument in the 
outCliannel parameter or n i 1 if an error occurs. 



NADisposeNoteChannel 



The NADisposeNoteChannel function deletes the specified note channel. 

pascal ComponentResul t NADi sposeNoteCiiannel ( 
NoteAnocator na, 
NoteCliannel noteCliannel ) ; 

n a You obtain the note allocator identifier from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

noteCliannel Note channel to be disposed. You obtain the note channel 
identifier from the NANewNoteCliannel or the 
NANewNoteCliannel FromAtomi cinstrument function. 

function result A result code. 



NAGetNoteChannellnfo 



The NAGetNoteClnannel Info function returns the index of the music component 
for the allocated channel and its part number on that music component. 

pascal ComponentResul t NAGetNoteCliannel Inf o( 
NoteAl 1 ocator na, 
NoteChannel noteChannel , 
long *index, 
long *part) ; 

n a You obtain the note allocator identifier from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 



Functions 



105 



CHAPTER 2 

Music Architecture Reference 



noteChannel Note channel to get information about. You obtain the note 
channel identifier from the NANewNoteChannel or the 
NANewNoteChannel FromAtomi cinstrument function. 

index Music component index. 

part Music component part pointer. 

function result A result code. 



DISCUSSION 

The NAGetNoteChannellnfo fimction allows direct access to the music component 
allocated to the note channel by the note allocator. The index returned becomes 
invalid if music components are subsequently registered or unregistered. 



NAGetlndNoteChannel 



The NAGetlndNoteChannel fimction returns the number of note channels handled 
by the specified note allocator instance. It can also return a requested note 
channel. 



extern pascal ComponentResul t NAGetlndNoteChannel ( 
NoteAl 1 ocator na, 
long index, 
NoteChannel *nc, 
1 ong *seed ) ; 



na You obtain the note allocator identifier from the Component 

Manager's OpenComponent fimction. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

index The index of the note channel. If zero, the result is still the 

number of note channels, but *nc is not filled out. 

n c The note channel requested. 

seed A number that changes on successive calls if anything 

significant changes about a note channel — for example, if the 
note channel has been reallocated or released. 
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function result Positive results are the index count; negative results are error 
codes. 



DISCUSSION 

To get a count of the note channels, pass the NAGetlndNoteChannel function in 
the index parameter. To get a specific note channel, pass the index value 
returned by a previous call to NAGetlndNoteChannel . 



NAUseDefaultMIDIInput 



The NAUseDefaultMIDI Input function defines an entry point to service external 
MIDI device events. This routine, in turn, calls the QuickTime MIDI 
components to query them. NAGetMIDI Ports is the correct call for you to make. 
You should not call QTM I D I . 

pascal ComponentResul t NAUseDefaultMIDIInput ( 
NoteAl 1 ocator na , 
MusicMIDIReadHookUPP readHook, 
long refCon, 
unsi gned 1 ong f 1 ags ) ; 

na You obtain the note allocator identifier from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

readHook Process pointer for MIDI service. 

r e f c n Contains a reference constant value. The Movie Toolbox passes 

this reference constant to youj error-notification function each 
time it calls your function. 

flags Must contain zero. 

function result A result code. 



DISCUSSION 

The NAUseDefaultMIDI Input function specifies an application's procedure to 
service external MIDI events. The specified application's procedure call, defined 
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by readHook, is called when the external default MIDI device has incoming 
MIDI data for the application. 



NALoseDefaultMIDIInput 



The NALoseDefaultMIDIInput function removes the external default MIDI service 
procedure call, if previously defined byNAUseDefaultMIDIInput. This routine, in 
turn, calls the QuickTime MIDI components to query them. NAGetMIDIPorts is 
the correct call for users to make. Users should not call QTM I D I . 

pascal ComponentResul t NALoseDefaultMIDIInput ( NoteAl 1 ocator na); 

na You obtain the note allocator identifier from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

function result A result code or - 1 if a default MIDI device was not in use. 



NAPreroUNoteChannel 



The NAPreroUNoteChannel fimction attempts to reallocate the note channel if it 
was invalid previously. 

pascal ComponentResul t NAPrerol 1 NoteChannel ( 
NoteAl 1 ocator na, 
NoteChannel noteChannel ) ; 

You obtain the note allocator identifier from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

Note channel to be re-allocated. You obtain the note channel 
identifier from the NANewNoteChannel or the 
NANewNoteChannel FromAtomi cinstrument function. 

function result A result code. 



na 



noteChannel 
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DISCUSSION 

The NAPrerollNoteClnannel function attempts to reallocate the note channel, if it 
was invalid previously. It could have been invalid if there were no available 
voices on any registered music components when the note channel was created. 



NAUnroUNoteChannel 



The NAUnrol 1 NoteClnannel function marks a note channel as available to be 
stolen. 

pascal ComponentResul t NAUnrol 1 NoteChannel ( 
NoteAl 1 ocator na , 
NoteCliannel noteCliannel ) ; 

na You obtain the note allocator identifier from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

noteCliannel Note channel to be unrolled . You obtain the note channel 
identifier from the NANewNoteChannel or the 
NANewNoteCliannel FromAtomi cinstrument function. 

function result A result code. 



NAResetNoteChannel 



The NAResetNoteChannel function turns off all currently "on" notes on the note 
channel and resets all controllers to their default values. 

pascal ComponentResul t NAResetNoteChannel ( 

NoteAl 1 ocator na , 
NoteChannel noteChannel ) ; 

na You obtain the note allocator identifier from the Component 

Manager's OpenComponent fimction. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 
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DISCUSSION 



noteChannel The note channel to reset. You obtain the note channel identifier 
from the NANewNoteChannel or the 
NANewNoteChannel FromAtomi cinstrument function. 

function result A resiilt code. 



The NAResetNoteChannel function resets the specified note channel by turning 
"off" any note currently playing. All controllers are reset to their default state. 
The effects of the NAResetNoteChannel call are propagated down to the allocated 
part within the appropriate music component. 



NASetNoteChannelVolume 



DISCUSSION 



The NASetNoteChannel Vol ume function sets the volume on the specified note 
channel. 

pascal ComponentResul t NASetNoteChannel Vol ume( 
NoteAl 1 ocator na, 
NoteChannel noteChannel , 
Fixed volume); 

n a You obtain the note allocator identifier from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

noteChannel The note channel to reset. You obtain the note channel identifier 
from the NANewNoteChannel or the 
NANewNoteChannel FromAtomi cinstrument function. 

volume The volume to set the channel to. The value is a fixed 16.16 

number. 



The NASetNoteChannel Vol ume function sets the volume for the note channel, 
which is different from a controller 7 (volume controller) setting. 
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Both volume settings allow fractional values of 0.0 to 1.0. Each value modifies 
the other. For example, a volume controller value of 0.5 and a 
NASetNoteCliannel Vol ume value of 0.5 result in a 0.25 volume level. 



NASetNoteChannelBalance 



The NASetNoteCliannel Bal ance function modifies the pan controller setting for a 
note channel. 

extern pascal ComponentResul t NASetNoteCliannel Bal ance( 
NoteAl 1 ocator na, 
NoteChannel noteChannel , 
1 ong bal ance ) ; 

You obtain the note allocator identifier from the Component 
Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

The note channel to be balanced. You obtain the note channel 
identifier from the NANewNoteChannel or the 
NANewNoteChannel FromAtomi cinstrument function. 

balance Specifies how to modify the pan controller setting. Valid values 

are from -128 to 128 for left to right balance. 

function result A result code. 



na 



noteChannel 



NASetNoteChannelSoundLocalization 



The NASetNoteCliannel SoundLocal i zati on function passes sound localization data 
to a note channel. 

extern pascal ComponentResul t NASetNoteCliannel SoundLocal i zati on( 
NoteAl 1 ocator na, 
NoteChannel noteChannel , 
Handl e data ) ; 
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na You obtain the note allocator identifier from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

noteChannel The note channel to pass the data to . You obtain the note 
channel identifier from the NANewNoteChannel or the 
NANewNoteChannel FromAtomi clnstrument function. 

data Sound localization data. 

function result A result code. 



NAPlayNote 



The NAPl ayNote function plays a note with a specified pitch and velocity on the 
specified note channel. 

pascal ComponentResul t NAPlayNote( 

NoteAl 1 ocator na, 
NoteChannel noteChannel , 
long pitch, 
long velocity); 

na You obtain the note allocator identifier from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

noteChannel The note channel to play the note. You obtain the note channel 
identifier from the NANewNoteChannel or the 
NANewNoteChannel FromAtomi clnstrument fimction. 

pitch The pitch at which to play the note. You can specify values as 

integer pitch values (0-127 where 60 is middle C) or fractional 
pitch values (256 (0x1 . 00) through 32767 (0x7 F . FF)). 

V e 1 c i ty The velocity with which the key is struck. A value of is silence; 
a value of 127 is maximum force. 

function result A result code. 
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DISCUSSION 

The NAPl ayNote function plays a specific note. If the pitch is a niimber from to 
127, then it is the MIDI pitch, where 60 is middle C. If the pitch is a positive 
nvmriber above 65535, then the value is a fixed-point pitch value. Thus, 
microtonal values can be specified. The range 256 (0x01 . 00) through 32767 
(0x7 F . F F), and all negative values, are not defined, and should not be used. 

The velocity refers to how hard the key was struck (if performed on a keyboard 
instrimient). Typically, this translates directly to volimie, but on many 
S5mthesizers this also subtly alters the timbre of the tone. 



NAGetControUer 



You use the NAGetControUer fimction to get the controller settings for a note 
channel. 

pascal ComponentResul t NAGetControl 1 er ( 
NoteAl 1 ocator na, 
NoteChannel noteChannel , 
long control 1 erNumber , 
long *control 1 erVal ue ) ; 

n a You obtain the note allocator identifier from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

noteCliannel Note channel for which to get controller settings . You obtain the 
note channel identifier from the NANewNoteChannel or the 
NANewNoteCliannel FromAtomi cinstrument function. 

control 1 erNumber 

The controller for which to get settings. For valid values, see 
"Controller Numbers" (page 56). 

control 1 erVal ue 

On return, the value for the controller setting, tj^ically 
(0x00 . 00) to 32767 (0x7 F . FF). 
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NASetController 



The NASetController function changes the controller setting on a note channel 
to a specified value. 

pascal ComponentResul t NASetController 
( NoteAl 1 ocator na, 
NoteChannel noteChannel , 
long control 1 erNumber , 
long control 1 erVal ue) ; 

n a You obtain the note allocator identifier from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

noteChannel Note channel on which to change controller. You obtain the note 
channel identifier from the NANewNoteChannel or the 
NANewNoteChannel FromAtomi cinstrument fiinction. 

control 1 erNumber 

The controller to set. For valid values, see "Controller Numbers" 
(page 56). 

control 1 erVal ue 

Value for controller setting, typically (0x00 . 00) to 32767 
(0x7F. FF). 



NAGetKnob 



Use the NAGetKnob function to get the value of a knob for a given note channel. 

extern pascal ComponentResul t NAGetKnob( 
NoteAl 1 ocator na, 
NoteChannel noteChannel , 
long knobNumber, 
long *knobValue); 

na You obtain the note allocator identifier from the Component 

Manager's OpenComponent fimction. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 
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noteChannel The note channel whose knob value you want to get. You obtain 
the note channel identifier from the NANewNoteChannel or the 
NANewNoteCliannel FromAtomi cinstrument function. 

knobNumber The index or ID of the knob whose value you want to get. 

knobVal ue On exit, the value of the knob. 

function result A result code. 



DISCUSSION 

The NAGetKnob function takes a note allocator component identifier in the na 
parameter, a note channel identifier in the noteChannel parameter, and 1lie knob 
index or ID in the knobNumber parameter. It returns, in the knobValue parameter, 
a pointer to the current value of the knob. 



NASetKnob 



The NASetKnob function sets a note channel knob to a particular value. 

pascal ComponentResul t NASetKnobC 

NoteAl 1 ocator na , 
NoteChannel noteChannel , 
long knobNumber, 
long knobValue); 



n a You obtain the note allocator identifier from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

noteChannel Note channel on which to set the knob value. You obtain the 
note channel identifier from the NANewNoteChannel or the 
NANewNoteChannel FromAtomi cinstrument function. 

knobNumber Index or ID of the knob to be set. 

knobVal ue Value to set knob to. 

function result A result code. 
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DISCUSSION 

The NASetKnob function takes a note allocator component identifier in the na 
parameter, a note channel identifier in the noteChannel parameter, the knob ID 
or index in the knobNumber parameter, and a knob value in the knobVal ue 
parameter. It sets the specified knob to the given value. 



NAFindNoteChannelTone 



The NAFindNoteChannelTone fimction locates the instrument that best fits a 
requested tone description for a specific channel. 

pascal ComponentResul t NAFi ndNoteChannel Tone( 
NoteAl 1 ocator na, 
NoteChannel noteChannel , 
ToneDescri pti on *td, 
long *i nstrumentNumber) ; 

You obtain the note allocator identifier from the Component 
Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

The note channel for which you want an instrument. You obtain 
the note channel identifier from the NANewNoteChannel or the 
NANewNoteChannel FromAtomi cinstrument function. 

td Description for instrument fit. 

i nstrumentNumber 

On exit, the number of the instrument that best fits the tone 
description. 

function result A result code. 



na 



noteChannel 



116 



Functions 



CHAPTER 2 

Music Architecture Reference 



NASetlnstrumentNumber 



The NASetlnstrumentNumber function initializes a synthesizer part with the 
specified instrument. 

pascal ComponentResul t NASetlnstrumentNumberC 

NoteAl 1 ocator na, 
NoteChannel noteChannel , 
long i nstrumentNumber ) ; 

n a You obtain the note allocator identifier from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

noteCliannel Note channel to initialize with the instrument. You obtain the 
note channel identifier from the NANewNoteChannel or the 
NANewNoteCliannel FromAtomi cinstrument function. 

i nstrumentNumber 

Number of the institiment to initialize the part with. This 
number is imique to each synthesizer. General MIDI 
S5mthesizers all share the range 1-128 and 16365 to 

kLastDrumKi t. 

function result A result code. 



NASetlnstrumentNumberlnterruptSafe 

You can use the NASetlnstrumentNumberlnterruptSaf e function to initialize a 
synthesizer part with the specified instrument diiring interrupt time. 

extern pascal ComponentResul t NASetlnstrumentNumberlnterruptSafeC 
NoteAl 1 ocator na, 
NoteCliannel noteCliannel , 
long i nstrumentNumber ) ; 

n a You obtain the note allocator identifier from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 
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noteChannel Note channel to initialize with the instrument. You obtain the 
note channel identifier from the NANewNoteChannel or the 
NANewNoteChannel FromAtomi cinstrument function. 

i nstrumentNumber 

Number of the instrtiment to initialize the part with. 

function result A result code. 



DISCUSSION 

If the instrument is not already loaded when you call the 

NASet I nstrumentNumber I nterruptSafe function, you have to wait for the next call 
to the NATask fxmction for the instrimient to become available. 



NASetAtomicInstrument 



The NASetAtomicInstrument function initializes a S5mthesizer part with an 
atomic instrimient. 

extern pascal ComponentResul t NASetAtomi clnstrument( 
NoteAl 1 ocator na, 
NoteChannel noteChannel , 
Atomi cinst rumen tPtr i nstrument , 
1 ong flags); 

na You obtain the note allocator identifier from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

noteChannel The note channel to apply the atomic instrument to. You obtain 

the note channel identifier from the NANewNoteChannel or the 
NANewNoteChannel FromAtomi cinstrument function. 

i nstrument A pointer to the atomic instrtiment. This can be a locked, 
dereferenced atomic instrument. 

flags Details about how to initialize the part. For a description of the 

flags, see "Flags for Setting Atomic Instruments" (page 63). 

function result A result code. 
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Use the NASendMIDI function to send a MIDI music packet to a synthesizer that 
contains a specific note channel. This routine, in turn, calls the QuickTime MIDI 
components to query them. NAGetMI DI Ports is the correct call for users to make. 
Users should not call QTM I D I . 



extern pascal ConiponentResul t NASendMIDK 
NoteAllocator na, 
NoteChannel noteChannel , 
MusicMIDIPacket *mp) ; 



n a You obtain the note allocator identifier from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

noteCliannel The function sends the packet to the synthesizer that contains 
this note channel. You obtain the note channel identifier from 
the NANewNoteClnannel or the 

NANewNoteCliannel FromAtomi cinstrument function, 
mp The music packet to be sent. 

function result A result code. 



DISCUSSION 

The NASendMIDI function sends the MIDI music packet pointed to by the mp 
parameter to the synthesizer that contains the note channel identified by the 
noteCliannel parameter. The na parameter specifies the note allocator instance to 
use. 



NAGetNoteRequest 



The NAGetNoteRequest fimction gets the note request passed to a note channel. 

extern pascal ConiponentResul t NAGetNoteRequest( 
NoteAl 1 ocator na, 
NoteChannel noteChannel , 
NoteRequest *nrOut) ; 
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na You obtain the note allocator identifier from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

noteChannel The note channel whose note request you want to get. You 

obtain the note channel identifier from the NANewNoteChannel or 
the NANewNoteChannel FromAtomi cinstrument function. 

n rOut On exit, a note request structure (page 86). 

function result A result code. 



DISCUSSION 

The NAGetNoteRequest function takes a note allocator instance in the na 
parameter and a note channel identifier in the noteChannel parameter. It returns, 
in the *nrOut parameter, the note request that was used to allocate the specified 
note channel. 



Note Allocator Functions: Miscellaneous Interface Tools 

The functions in this section provide a user interface for instrument selection 
and presenting copyright information. 



NAPicklnstrument 



The NAPicklnstrument function presents a user interface for picking an 
instrument. 

pascal ComponentResul t NAPi cklnstrument( 
NoteAl 1 ocator na, 
Modal Fi 1 terUPP filterPnoc, 
StringPtr prompt, 
ToneDescri pti on *sd, 
unsigned long flags, 
long refCon, 
long reservedl, 
1 ong reserved2) ; 
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na You obtain the note allocator identifier from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

filterProc Standard modal filter universal procedure pointer. 

prompt Dialog box prompt "New Instrument". 

sd On entry, the tone description of the instrument that appears in 

the picker dialog box. On exit, a tone description of the 
instrument the user selected. 

flags Determines whether to display the picker dialog box and what 

instruments appear for selection. See "Pick Instrument Flags" 
(page 67). 

r e f c n Contains a reference constant value. The Movie Toolbox passes 

this reference constant to youi error-notification function each 
time it calls youj function. 

reservedl Must contain zero. 

reserved2 Must contain zero . 

function result A result code or - 1 if there is a problem opening the dialog box. 



The flags values limit which instruments appear within the dialog box. If the 
kPickDontMix flag is set, the dialog box does not display a iiux of synthesizer 
part t5^es. For example, if the current instrument is a drum, only available 
drimis appear in the dialog box. The kPi ckSameSynth flag allows selections only 
within the current synthesizer. The kPickUserlnsts flag allows user modifiable 
instruments to appear. 



SEE ALSO 



NAPickEdit Instrument function 
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NAPickEditlnstrument 



The NAPickEditlnstrument function presents a user interface for changing the 
instrument in a live note channel or modifying an atomic instrument. 

extern pascal ComponentResul t NAP1cl<Ed1tInstrument( 

NoteAl 1 ocator na, 

Modal F11 terUPP fllterProc, 

StrlngPtr prompt, 

long refCon, 

NoteChannel nc, 

Atomi cinstrument a1 , 

1 ong f 1 ags ) ; 



n a You obtain the note allocator identifier from the Component 

Manager's OpenComponent fimction. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

fllterProc Standard modal filter universal procedure pointer. 

prompt Dialog box prompt "New Instrument". 

r e f C n Contains a reference constant value. The Movie Toolbox passes 

this reference constant to your error-notification function each 
time it calls your function. 

n c The live note channel that appears in the dialog box. If you 

specify a note channel, set the a 1 parameter to 0. You obtain the 

note channel identifier from the NANewNoteChannel or the 
NANewNoteChannel FromAtomi cinstrument function. 

a 1 The atomic instrument that appears in the dialog box. If you 

specify an atomic instrument, set the nc parameter to 0. You 
obtain the atomic instrument from the InstrumentGetlnst 
function. 

flags Flags limiting the instruments presented. See "Pick Instrtiment 

Flags" (page 67) 

function result A result code or -1 if there is a problem opening the dialog box. 
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DISCUSSION 



SEE ALSO 



The flags value limits which instruments appear within the dialog box. If the 

kPickDontMix flag is set, the dialog box does not display a mix of s}mthesizer 
part types. For example, if the current instrviment is a drvim, only available 
drtims appear in the dialog box. The kPi ckSameSynth flag allows selections only 
within the current synthesizer The kPickUserlnsts flag allows user modifiable 
instruments to appear If the kPi ckEdi tAl 1 owPi ck flag is not set, no dialog box 
appears. 



NAPi cklnstrument function 



The NAStuf fToneDescri pti on function initializes a tone description structure 
with the details of a General MIDI note channel. 

pascal ConiponentResul t NAStuffToneDescription( 



NAStuffToneDescription 



NoteAl 1 ocator na, 
long gmNumber, 
ToneDescri pti on *td); 



na 



You obtain the note allocator identifier from the Component 
Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 



gmNumber 



A General MIDI instrument niimber. 



td 



On exit, an initialized tone description. The instrument name 
field will be filled in with the string name for the instrviment. 



function result A result code. 
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NAPickArrangement 



The NAPi ckArrangement function displays a dialog box to allow instrument 
selection. 

pascal ComponentResul t NAPi cl<Arrangement( 

NoteAl 1 ocator na, 

Modal Fi 1 terUPP filterProc, 

StringPtr prompt, 

long zerol, 

long zero2, 

Tracl< t, 

StringPtr songName); 



n a You obtain the note allocator identifier from the Component 

Manager's OpenComponent fimction. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

filterProc Standard modal filter universal procedure pointer. 

prompt Dialog box prompt. 

zerol Must be 0. 

zero2 Must be 0. 

t Arrangement movie track ntraiber 

songName Name of song to display in dialog box. 



function result A result code or - 1 if there is a problem opening the dialog box. 



NACopyrightDialog 



The NACopyri ghtDi al og fimction displays a copyright dialog box with 
information specific to a music device. 

pascal ComponentResul t NACopyri ghtDi al og( 
NoteAl 1 ocator na, 
PicHandle p, 
StringPtr author, 
StringPtr copyright. 
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StringPtr otiier, 
StringPtr title, 
Modal FilterUPP filterProc, 
1 ong ref Con ) ; 

You obtain the note allocator identifier from the Component 
Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

Picture image resource handle for dialog box. 

Author information. 

Copyright information. 

Any additional information. 

Title information. 

Standard modal filter universal procedure pointer. 

Contains a reference constant value. The Movie Toolbox passes 
this reference constant to your error-notification function each 
time it calls youjr function. 

A result code or -1 if there is a problem opening the dialog box. 



P 

autlior 
copyri gilt 
otiier 
title 

f i 1 terProc 
ref con 

function result 



Note Allocator Functions: System Configuration and Utility 

Use the functions in this section to create and maintain a database of music 
components, to save configuration information in the QuickTime Preferences 
file, to establish connections to external MIDI devices, and to allow the note 
allocator to perform necessary tasks at task foreground time. 
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NARegisterMusicDevice 



The NARegi sterMusi cDevi ce function registers a music component with the note 
allocator. 

pascal ComponentResul t NARegi sterMusi cDevi ce( 

NoteAl 1 ocator na, 
OSType synthType, 
Str31 name, 

SynthesizerConnections *connections); 

n a You obtain the note allocator identifier from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

synthType Subt5^e of the music component. 

name The synthesizer name. 

connections A synthesizer connection structure (page 84) that describes how 
a MIDI device is connected. 



function result A result code. 



DISCUSSION 

The value of the synthType parameter is the music component's subtype. The 
name parameter provides a means of distinguishing multiple instances of the 
same type of device and is a string that can be displayed to the user. If no value 
is passed in the name parameter, the name defaults to the name of the music 
component t3^e. The name appears in the instrument picker dialog box. 

The connections parameter specifies the hardware connections to the device. 
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RESULT CODES 

Syntliesi zerErr If too many synthesizers registered. 

midiManagerAbsentErr If MIDI not available. 



NAUnregisterMusicDevice 



The NAUnregisterMusicDevice function removes a previously registered music 
component from the note allocator. 

pascal ComponentResul t NAUnregi sterMusi cDevi ce( 
NoteAl 1 ocator na, 
long index) ; 

n a You obtain the note allocator identifier from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

i ndex Synthesizer to unregister. The value is 1 through the registered 

music component coimt returned by the 
NAGetRegi steredMusi cDevi ce function (page 127). 

function result A result code. In addition to QTMA result codes, this function 
may return a result code from the CI oseComponent function. 



NAGetRegisteredMusicDevice 



The NAGetRegisteredMusicDevice function returns specifics about music 
components registered to the specified note allocator instance. 

pascal ComponentResul t NAGetRegi steredMusi cDevi ce( 
NoteAl 1 ocator na, 
long index, 
OSType *syntliType, 

Str31 name, 

SynthesizerConnections *connections, 
Musi cComponent *mc); 
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na 



You obtain the note allocator identifier from the Component 
Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 



i ndex 



The index of the music component to get information about or 
to get the total number of music components registered with the 
note allocator. 



name 



synthType 



S5mthesizer type. 

Synthesizer name as a text string. 



connecti ons A sjmthesizer connections for MIDI devices structure (page 84). 



function result Positive values are the number of music components registered 
with the note allocator; negative values are result codes. 



To get a coimt of the registered music components, pass the 

NAGetRegi steredMusi cDevi ce function in the index parameter. The return value 

is the count of components. To get information about one of the music 

components registered with the note allocator, pass the music component index 

in the i ndex parameter. The index value can be 1 through the number of 

registered components returned by a previous call to 

NAGetRegi SteredMusi cDev ice. 

If you request information about a specific registered music component, the 
NAGetRegi steredMusi cDevi ce fimction returns the type of synthesizer the 
component supports in the synthType parameter, the name of the synthesizer in 
the name parameter, and the music component identifier in the mc parameter. For 
MIDI devices, it returns a pointer to a MIDI devices structure with information 
about the synthesizer connections. 



The NAGetDefaultMlDllnput function is used to obtain external MIDI connection 
information. This routine, in turn, calls the QmckTime MIDI components to 



mc 



Music component instance identifier. 



DISCUSSION 



NAGetDefaultMlDllnput 
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query them. NAGetMIDI Ports is the correct call for you to make. You should not 
call QTMIDI. 

pascal ComponentResul t NAGetDef aul tMIDI Input( 
NoteAl 1 ocator na, 
Syntliesi zerConnecti ons *sc); 

na You obtain the note allocator identifier from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

s c On exit, a S5mthesizer connection structure (page 84) that 

describes how a MIDI device is connected. 



DISCUSSION 

The NASGetDef aul tMIDI Input function returns an initialized 
SynthesizerConnections structure containing information about the external 
MIDI device attached to the system Hhat has been selected as the default MIDI 
input device. The external MIDI device provides note input directly to the note 
allocator. 



NASetDefaultMIDIInput 



The NASetDefaultMIDIInput function initializes an external MIDI device used to 
receive external note input.This routine, in turn, calls the QuickTime MIDI 
components to query them. NAGetMlDlPortsis the correct call for users to make. 
Users should not call QTM I D I . 

pascal ComponentResul t NASetDef aul tMIDIInputC 

NoteAl 1 ocator na, 
SynthesizerConnections *sc); 

n a You obtain the note allocator identifier from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

s c A synthesizer connection structiire (page 84) that describes how 

a MIDI device is connected. 
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DISCUSSION 

The SynthesizerConnections structure fields cl ientID, inputPortlD, and 
outputPortID are MIDI Manager identifiers. The m i d i C h a n n e 1 field is the MIDI 
system channel value. 

function result A result code. 



NAGetMIDIPorts 



The NAGetMIDIPorts function gets the MIDI input and output ports available to a 
note allocator This routine, in turn, calls the QuickTime MIDI components to 
query them. NAGetMIDIPorts is the correct call for you to make. You shoijld nof 
call QTMIDI. 



extern pascal ComponentResul t NAGetMIDIPorts( 
NoteAl 1 ocator na, 
QTMIDIPortListHandl e *input Ports , 
QTMIDI Port Li stHandle *outputPorts ) ; 

n a You obtain the note allocator identifier from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

inputPorts On exit, a handle giving the number of input ports (the first two 
bytes) followed by a list of QuickTime MIDI port structures 
(page 85). 

outputPorts On exit, a handle giving the number of output ports (the first 

two bytes) followed by a list of QuickTime MIDI port structures 
(page 85). 

function result A result code. 
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NASaveMusicConfiguration 



TheNASaveMusicConfiguration saves the ciirrent list of registered devices to a 
file. 

pascal ComponentResul t NASaveMusicConfiguration ( NoteAl 1 ocator na); 

n a You obtain the note allocator identifier from the Component 

Manager's OpenCoinponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 

function result A result code or -1 if there is a problem opening or creating the 
QuickTime Preferences file. 



DISCUSSION 



TheNASaveMusicConfiguration fimction saves the current list of registered 
devices to a file. This file is read whenever a note allocator connection is 
opened, restoring the previously configured list of devices. The list is saved in 
the QuickTime Preferences file. 



NATask 



Call the NATas k fimction periodically to allow the note allocator to perform tasks 
in foregrovind task time. 

extern pascal ComponentResul t NATask ( NoteAl 1 ocator na); 

na You obtain the note allocator identifier from the Component 

Manager's OpenComponent function. See the chapter "Component 
Manager" in QuickTime 3 Reference for details. 



DISCUSSION 



function result A result code. 



The NATask function calls each registered music component's Musi cTask 
fimction. 
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Music Component Functions: Synthesizer 

The functions in this section obtain specific information about a synthesizer and 
obtain a best instrument fit for a requested tone from the available instnmients 
within the S5mthesizer; play a note with a specified pitch, volume, and duration; 
get and set a particular synthesizer knob; obtain synthesizer knob information; 
and get and set external MIDI procedure name entry points. 



MusicGetDescription 



The Musi cGetDescn'pt ion function retiims a structure describing the synthesizer 
controlled by the music component device. 

pascal ComponentResul t Musi cGetDescri pti on ( 
Musi cComponent mc, 
Synthesi zerDescri pti on *sd); 

mc Music component instance identifier returned by 

NAGetRegi steredMusi cDevi ce. 

sd Pointer to S5mthesizer description structure (page 73). 

function result A result code. 



DISCUSSION 

The Musi cGetDescri pti on fimction retiirns a structiire describing the specified 
music component device. The Synthesi zerDescri pti on structure is filled out by 
the particular music component. 
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MusicFindTone 



The MusicFindTone function retiims an instrument number based on a tone 
description. 

pascal ComponentResul t MusicFindToneC 

Musi cComponent mc, 
ToneDescri pti on *td, 
long *1 i brary IndexOut , 
unsi gned 1 ong *f i t ) ; 

mc Music component instance identifier returned by 

NAGetRegisteredMusicDevice. 

td Pointer to a tone description structure (page 75). 

1 ibrarylndexOut 

On exit, contains the number of the best-matching instrument. 
Only General MIDI numbers are guaranteed to be the same for 
later instantiations of the component. 

f i t On exit, indicates how well an instrument matches the tone 

description. For valid values, see "Tone Fit Flags" (page 59). 

function result A result code. 



DISCUSSION 

The MusicFindTone fimction returns the number of the best-matching instrument 
provided by the specified music component. The closeness of the match is 

specified by the f 1 1 parameter. 

The music component searches for an instrument as follows: 

1. If the synthesi zerType field of the td parameter matches the t5^e of the 
specified music component, it first tries to find an instrirment that matches 
the value of the i nstrumentNumber field of the td parameter. If this value is in 
the range 129-16512, which specifies a GS instrument, and the GS instrviment 
is not available, it tries to find the General MIDI instrument that corresponds 
to it, which has the number ((GSi nstrumentnumber - 1) & 0x7F) + 1)). If the 
value is greater than 16512, which specifies a transient ROM instrimient or 
internal instrument index value, it tries to find an instrument that matches 
the syntlnes i zerName field of the td parameter If that fails, it tries to find an 
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instrument that matches the value of the value of the gmNumber field of the td 
parameter. 

2. If the synthesizerType field of the td parameter does not match the type of 
the specified music component, it tries to find an instrument that matches the 
value of the gmNumber field of the td parameter. 

If none of these rules apply, or the fields are "blank" (zero for the type or 
numeric fields, or zero-length for the strings), then the call returns instrument 1 
and a fit value of zero. The synthesizerName field may be ignored by the 
component; it is used by the note allocator when deciding which music device 
to use. 



MusicPlayNote 



The Musi cPl ayNote function plays a note on a specified part at a specified pitch 
and velocity. 

pascal ComponentResul t Musi cPl ayNote( 

Musi cComponent mc, 
long part, 
long pitch, 
long velocity); 

mc Music component instance identifier returned by 

NAGetRegi steredMusi cDevi ce. 

part The part to play the note on. 

pitch The pitch at which to play the note. Values are 0-127 for MIDI 

pitch or greater than 65535 for microtonal values. 

vel oci ty How hard to strike the key. Values are 0-127 where is silence. 

function result A resixlt code. 

DISCUSSION 

The Musi cPl ayNote function is used to play notes by their pitch. If the pitch is 
specified by a number from to 127, it is a MIDI pitch, where 60 is middle C. If 
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the pitch is a positive number above 65535, the value is a fixed-point pitch 
value. Thus, microtonal values may be specified. 

Velocity refers to how hard the key is struck (if performed on a 
keyboard-instrument); t3^ically, this translates directly to volume, but on many 
S5mthesizers this also subtly alters the timbre of the tone. 

The current note continues to play until aMusicPlayNote function with the same 
pitch and velocity of turns the note off. 



MusicGetKnob 



The MusicGetKnob function returns the value of the specified global S5mthesizer 
knob. A global knob controls an aspect of the entire sj^thesizer. It is not specific 
to a part within the synthesizer. 

pascal ComponentResul t Musi cGetKnob( 

Musi cComponent mc, 
1 ong knobID) ; 

mc Music component instance identifier returned by 

NAGetRegi steredMusi cDevi ce. 

knob I D Knob index or ID. 

function result A result code. 



MusicSetKnob 



The Musi cSet Knob fimction modifies the value of the specified global synthesizer 
knob. A global knob controls an aspect of the entire sjmthesizer. It is not limited 
to a part within the S5mthesizer. 

pascal ComponentResul t Musi cSetKnobC 

Musi cComponent mc, 
long knobID, 
long knobValue); 
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mc Music component instance identifier returned by 

NAGetRegi steredMusi cDevi ce. 

!< n b I D Knob index or ID. 

l<nobValue Value for specified knob. 
function result A resiilt code. 



MusicGetKnobDescription 



The Musi cGetKnobDescri pti on function returns a pointer to an initialized knob 
description structure describing a global synthesizer knob. A global knob 
controls an aspect of the entire synthesizer; it is not limited to a part within the 
S5mthesizer. 

pascal ComponentResul t Musi cGetKnobDescri pti on ( 
Musi cComponent mc, 
long knoblndex, 
KnobDescri pti on *mkd); 

mc Music component instance identifier returned by 

NAGetRegi SteredMusi cDev ice. 

knoblndex Knob index or ID. 

mkd Pointer to a knob description structure (page 78). 

function result A resiilt code. 



DISCUSSION 

The initialized KnobDescri pti on structure provides the application default 
values associated with the particular knob. You can use the information 
returned by a call to the Musi cGetKnobDescri pti on function to reset a knob to 
some known, usable value. 
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MusicGetlnstrumentKnobDescription 



The Musi cGetlnstrumentKnobDescri pti on function gets the description of an 
instrument knob. 

extern pascal ComponentResul t MusicGetlnstrumentKnobDescriptionC 
Musi cComponent mc, 
long knoblndex, 
KnobDescri pti on *mkd); 

mc Music component instance identifier returned by 

NAGetRegi steredMusi cDevi ce. 

knoblndex A knob index or knob ID. 

mkd On exit, a knob description structure (page 78). 

function result A result code. 



DISCUSSION 



The Musi cGetlnstrumentKnobDescri pti on function takes a music component 
instance identifier in the mc parameter and a knob index or knob ID in the 
knoblndex parameter. It returns a knob description structure in the mkd 
parameter. 



MusicGetDrumKnobDescription 



The Musi cGetDrumKnobDescri pti on function returns a description of a drum kit 
knob. 

extern pascal ComponentResul t MusicGetDrumKnobDescriptionC 

Musi cComponent mc, 
long knoblndex, 
KnobDescri pti on *mkd); 

mc Music component instance identifier returned by 

NAGetRegi steredMusi cDevi ce. 

knoblndex A knob index or knob ID. 
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mkd A pointer to a knob description structure (page 78). 

function result A result code. 

DISCUSSION 

The MusicGetDrumKnobDescn'ption function takes a music component in the mc 
parameter and a knob index or knob ID in the knoblndex parameter. It returns a 
knob description structure in the *mkd parameter. 



MusicGetKnobSettingStrings 



The MusicGetKnobSettingStrings function returns a list of knob setting names 
known by the specified music component. 

extern pascal ComponentResul t MusicGetKnobSettingStrings( 
Musi cComponent mc, 
long knoblndex, 
1 ong i sGl obal , 
Handle *setti ngsNames , 
Handle *setti ngsCategory Lasts , 
Handle *setti ngsCategoryNames ) ; 



mc Music component instance identifier returned by 

NAGetRegi steredMusi cDevi ce. 

knoblndex The knob index or knob ID. 

i s G 1 b a 1 If a knob index is used, indicates whether the specified knob is a 
global knob. 

setti ngsNames 

The requested list of knob setting strings formatted as a short 
followed by packed strings. 

setti ngsCategory Lasts 

A group of short integers, the first of which contains the number 
of shorts to follow. 
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settingsCategory Names 

Knob setting category names formatted as a short followed by a 
list of names. 

function result A result code. 
Note 

All handles must be disposed of by the caller. 



TheMusicSetMlDlProc function tells the music component what procedure to 
call when it needs to send MIDI data. This call is implemented only by a music 
component for a MIDI S5mthesizer. 

pascal ComponentResul t MusicSetMIDIProc( 



midiSendProc A pointer to the procedure to use when sending MIDI data. 



MusicSetMIDIProc 



Musi cComponent mc, 

Musi cMIDISendUPP mi di SendProc , 

1 ong ref Con ) ; 



mc 



Music component instance identifier returned by 

NAGetRegisteredMusicDevice. 



ref con 



Contains a reference constant value. The Movie Toolbox passes 
this reference constant to your error-notification function each 
time it calls your function. 



function result 



A result code. 
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MusicGetMIDIProc 



The MusicGetMIDIProc function returns a pointer to the procedure amusic 
component is using to process external MIDI notes. 

pascal ComponentResul t MusicGetMIDIProc( 

Musi cComponent mc, 
MusicMIDISendUPP *midiSendProc, 
1 ong *ref Con ) ; 

mc Music component instance identifier returned by 

NAGetRegi steredMusi cDevi ce. 

mi di SendProc 

Pointer to a MIDI serial port call. 

r e f c n Contains a reference constant. The Movie Toolbox passes this 

reference constant to your error-notification function each time 
it calls your fimction. 

function result A result code. 



DISCUSSION 

The MusicGetMIDIProc function returns, in the mi di SendProc parameter, a pointer 
to the function that processes external MIDI notes. This function was set by a 
previous call to the MusicSetMlDlProc function. If no fimction has been set with 
the Musi cSetMIDI Proc function, Musi cGetMIDIProc returns zero in the 
mi di SendProc parameter. 



MusicGetMIDIPorts 



The MusicGetMIDIPorts function returns the number of input and output ports a 
MIDI device has. 

extern pascal ComponentResul t MusicGetMIDIPorts( 
Musi cComponent mc, 
long *i nputPortCount , 
long *outputPortCount) ; 
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mc Music component instance identifier returned by 

NAGetRegi steredMusi cDevi ce. 

i nputPortCount 

On exit, the number of input MIDI ports available to the music 
component. 

outputPortCount 

On exit, the number of output MIDI ports available to the music 
component. 

function result A result code. 



DISCUSSION 

The fimction takes a music component identifier in the mc parameter and 
returns, in the i nputPortCount and outputPortCount parameters, the number of 
MIDI input and output ports available to the music component. 

This call is implemented only for a hardware synthesizer, such as a NuBus or 
PCI card device. 



MusicSendMIDI 



Use the MusicSendMIDI function to send a MIDI packet to a specified port. 

extern pascal ComponentResul t Musi cSendMIDI ( 

Musi cComponent mc, 
long portlndex, 
MusicMIDIPacket *mp) ; 

mc Music component instance returned by 

NAGetRegi steredMusi cDevi ce. 

portlndex The index of 1lie port to send the MIDI packet to. The index 
value is 1 through the port coimt returned by the 

Music GetMIDIPorts function. 

mp The music MIDI packet to be sent. 

function result A result code. 
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DISCUSSION 

The MusicSendMIDI function takes a music component in the m c parameter and a 
port index in the portlndex parameter. It sends the MIDI music packet specified 
by the inp parameter to the specified port. 

This call is implemented only for a hardware synthesizer, such as a NuBus or 
PCI card device. 



MusicGetDeviceConnection 



You can use the Musi cGetDevi ceConnecti on fimction to find out how many 
hardware synthesizers are available to a music component and to get the IDs 
for those devices. 

extern pascal ComponentResul t Musi cGetDevi ceConnecti on ( 
Musi cComponent mc, 
long index, 
long *idl, 
long *id2); 



mc 



Music component returned by NAGetRegi steredMusi cDevi ce. 



i ndex Index of the device for which you want to find out the IDs. Set 

to if you are calling to get the number of hardware devices. 

i d 1 On exit, a hardware S5mthesizer ID. 

i d 2 On exit, another hardware synthesizer ID. 

function result A result code. 



DISCUSSION 

To get the number of hardware synthesizers available to the music component 
specified in the mc parameter and an index you can use to request ID ntraibers 
for a specific device, call the MusicGetDeviceConnection function with a value of 
for the i ndex parameter. You can then pass an index value in the i ndex 
parameter, and the function returns hardware synthesizer IDs in the i d 1 and i d 2 
parameters. 
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This call is implemented only for a hardware S5mthesizer, such as a NuBus or 
PCI card device. 



MusicUseDeviceConnection 



The MusicUseDeviceConnection function tells a music component which 
hardware synthesizer to talk to. 

extern pascal ComponentResul t MusicUseDeviceConnection( 
Musi cComponent mc, 
long idl, 
long id2) ; 

mc Music component instance identifier returned by 

NAGetRegi steredMusi cDevi ce. 

i d 1 The ID of the device returned in the * i d 1 parameter of the 

Musi cGetDevi ceConnecti on function. 

i d2 The ID of the device returned in the *i d2 parameter of the 

Musi cGet Devi ceConnecti on ftmction. 



DISCUSSION 



function result A result code. 



This call is implemented only for a hardware S5mthesizer, such as a NuBus or 
PCI card device. 



Music Component Functions: Instruments and Parts 

The fimctions described in this section initialize a part with an instrument, store 
instruments, list available instruments, manipulate parts, and get information 
about parts. 
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MusicGetPartlnstrumentNumber 



The MusicGetPartlnstrumentNumber function retiims the instrument niraiber 
currently assigned to that part. 

pascal ComponentResul t Musi cGetPartInstrumentNumber( 

Musi cComponent mc, 
1 ong part); 

mc Music component instance identifier retiirned by 

NAGetRegi steredMusi cDevi ce. 

part Part number containing instrument. 

function result A positive return value is the instrument number; a negative 
value is a result code. 

MusicSetPartlnstrumentNumber 



The MusicSetPartlnstrumentNumber function initializes a part with a particular 
instrument. 

pascal ComponentResul t Musi cSetPartInstrumentNumber( 
Musi cComponent mc, 
long part, 

long i nstrumentNumber) ; 

mc Music component instance identifier returned by 

NAGetRegi steredMusi cDevi ce. 

part Part to be initialized. 

i nstrumentNumber 

Number of instrument to initialize part with. 

function result A resiilt code. 

DISCUSSION 

You can use the MusicFindTone function (page 133) to find out an instrument 
number. 
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This function is superseded by Musi cSetPartlnstrumentNumberlnterruptSafe, 
which can be called at interrupt time. You cannot call 
MusicSet Part Instrument Number at interrupt time. 



MusicSetPartlnstrumentNumberlnterruptSafe 



The Musi cSet Part Instrument Number Inter ruptSafe function initializes a part with 
a particular instrument. 

pascal ComponentResul t Musi cSetPartlnstrumentNumberC 
Musi cComponent mc, 
long part, 

long i nstrumentNumber ) ; 

mc Music component instance identifier returned by 

NAGetRegi steredMusi cDevi ce. 

part Part to be initialized. 

i nstrumentNumber 

Number of instnraient to initialize part with. 

function result A result code. 

DISCUSSION 

You can use the Musi cFi ndTone function (page 133) to find out an instrument 
number. 

You can call the Musi cSetPartlnstrumentNumberlnterruptSafe function at 
interrupt time. 
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MusicGetPartAtomicInstrument 



The MusicGetPartAtomicInstrument function retiims the atomic instrument 
currently in a part. 

extern pascal ComponentResul t Musi cGetPartAtomI clnstrument( 
Musi cComponent mc, 
long part, 

Atomi cinstrument *ai , 
1 ong f 1 ags ) ; 

mc Music component instance identifier returned by 

NAGetRegisteredMuslcDevice. 

part The part with the atomic instrument, 

a i On exit, an atomic instrument. 

flags Specify what pieces of information about an atomic instrument 

the caller is interested in. See "Atomic Instrument Information 
Flags" (page 63). 

function result A result code. 



MusicSetPartAtomicInstmment 



The MusicSetPartAtomicInstrument function initializes a part with an atomic 
instrument. 

extern pascal ComponentResul t Musi cSetPartAtomi clnstrument( 
Musi cComponent mc, 
long part, 

Atomi cInstrumentPtr aiP, 
1 ong f 1 ags ) ; 

mc Music component instance identifier returned by 

NAGetRegi steredMusi cDevi ce. 

part The part to initialize with the atomic instrument to. 

a i P The atomic instrument. 
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flags These flags specify details of initializing a part with an atomic 

instmment. See "Flags for Setting Atomic Instruments" on 
page 63. 

function result A result code. 



MusicStorePartlnstrument 



The MusicStorePartlnstrument function puts whatever instrument is on the 
specified part into the S5mthesizer's instrument store. This enables you to store 
modified instruments. 

pascal ComponentResul t Musi cStorePartInstrument( 
Musi cComponent mc, 
long part, 

long i nstrumentNumber ) ; 

mc Music component instance identifier returned by 

NAGetRegi steredMusicDevice. 

part Part containing the instriunent to be stored. 

i nstrumentNumber 

Instrument number at which to store the part. 

function result A result code. 

DISCUSSION 

The value of the I nstrumentNumber parameter must be between 1 and the 

synthesizer's modifiable instrument count, as defined by the 
modifiablelnstrumentCount field of the S5mthesizer 's description structure. 
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MusicGetlnstrumentAboutlnfo 



The MusicGetlnstrumentAboutlnfo function gets the information about an 
instrument that appears in its About box. 

pascal ComponentResul t Musi cGetInstrumentAboutInfo( 
Musi cComponent mc, 
long part, 

InstrumentAboutlnfo *iai); 

mc Music component instance identifier returned by 

NAGetRegi steredMusi cDevi ce. 

part Number of the part containing the instrument for which you 

want information. 

i a i On exit, a pointer to an instrument About information structure 

(page 78) for the instrument currently on the specified 
synthesizer part. 



MusicGetlnstrumentlnfo 



The MusicGetlnstrumentlnfo function gets a list of instruments supported by a 
synthesizer. It also gets the names of the instruments. 

extern pascal ComponentResul t Musi cGetInstrumentInfo( 
Musi cComponent mc, 
long getlnstrumentinf oFl ags , 
Instrument Info Li stHandle *infoListH); 

mc Music component instance identifier returned by 

NAGetRegi steredMusi cDevi ce. 

get Instrument I nfoFl ags 

Use these flags to specify whether you want a list of fixed 
instrimients, modifiable instrtiments, or all instrtiments. See 
"Instrument Info Flags" (page 64). 

i n f L i s t H On exit, the list of instruments (page 80). 

function result A result code. 
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Note 

This handle must be disposed of by the caller. 

DISCUSSION 

The functions takes a music component in the mc parameter and instructions 
regarding which types of instriiments to get information for in the 
get Instrument Names Fl ags parameter. It returns a handle to an instrument 
information list in the i nf oLi stH parameter. 



MusicGetPart 



The MusicGetPart function returns the MIDI channel and maximum pol5^hony 
for a particular part in the MIDIChannel and polypliony parameters. 

pascal ComponentResul t Musi cGetPartC 

Musi cComponent mc, 
long part, 
long *MIDICIiannel , 
long *polypliony) ; 

mc Music component instance identifier returned by 

NAGetRegi steredMusi cDevi ce. 

part The music component part requested. 

MIDICIiannel On exit, a pointer to a MIDI channel, 

polypliony On exit, a pointer to the maximum polyphony. 

function result A result code. 



DISCUSSION 

For non-MIDI devices, the MIDI channel pointed to by the MIDIChannel 
parameter is 0. 
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MusicSetPart 



The MusicSetPart function sets the MIDI channel and maximum poljrphony for 
the specified part to the values in the MIDIChannel and polyphony parameters. 

pascal ComponentResul t Musi cSetPart( 

Musi cComponent mc, 
long part, 
1 ong MIDIChannel , 
long polyphony); 

mc Music component instance identifier returned by 

NAGetReglsteredMusicDevice. 

part Part whose MIDI channel and pol5^hony are to be set. 

MIDIChannel The MIDI channel to set the part to. 

polyphony The maximum voices or polyphony for the part. 

function result A result code. 



DISCUSSION 



For non-MIDI devices, set the MIDI channel pointed to by the MIDIChannel 
parameter to 0. 



MusicGetPartName 



The MusicGetPartName function returns the string name of a part. 

pascal ComponentResul t MusicGetPartName( 
Musi cComponent mc, 
long part, 
StringPtr name); 

mc Music component instance identifier returned by 

NAGetReglsteredMusicDevice. 

part Part to get name of. 



150 



Functions 



CHAPTER 2 

Music Architecture Reference 

name On exit, the string containing the part name. 

function result A result code. 

DISCUSSION 

The name string is used by selection dialog boxes or configuration information. 



MusicSetPartName 



You can use the MusicSetPartName function to change the name of an instrimient 
in a specified part. For example, you might want to change the name of a 
modified instrument before saving it. 

pascal ComponentResul t Musi cSetPartNameC 
Musi cComponent mc, 
long part, 
Stri ngPtr name ) ; 

mc Music component instance identifier returned by 

NAGetRegi steredMusi cDevi ce. 

part Part to apply name to. 

name Name to apply to part. 

function result A result code. 

DISCUSSION 

The instrimient name string is used by selection dialog boxes or in 
configuration information. 
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MusicGetPartKnob 



The MusicGetPartKnob function gets the current value of a knob for a part. 

pascal ComponentResul t MusicGetPartKnob( 
Musi cComponent mc, 
long part, 
1 ong knobID) ; 

mc Music component instance identifier retiirned by 

NAGetRegi steredMusi cDevi ce. 

part The part number. 

l<nobID The knob index or ID. 

function result Positive or negative integers are knob values. Result codes are 
returned as OxSOOOxxxx, where xxxx is the result code. 



MusicSetPartKnob 



The MusicSetPartKnob function sets a knob for a specified part. 

pascal ComponentResul t MusicSetPartKnob( 
Musi cComponent mc, 
long part, 
long knobID, 
long knobValue); 

mc Music component instance identifier returned by 

NAGetRegi steredMusi cDevi ce. 

part The part number. 

knobID The index or ID of the knob to be set. 

knobValue The value to set the knob to. 

function result A resiilt code. 
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MusicResetPart 

The MusicResetPart function silences all soiinds on the specified part, and resets 
all controllers on that part to their default values. . 

pascal ComponentResul t MusicResetPartC 
Musi cComponent mc, 
long Part) ; 

mc Music component instance identifier returned by 

NAGetRegi steredMusi cDevi ce. 

part The number of the part. 

function result A result code. 

DISCUSSION 

The default value is for all controllers except volume. Volume is set to its 
maximum 32767 or, in hexadecimal, 7FFF. 



MusicGetPartController 



The Musi cGetPartControl 1 er function returns the value of the specified 
controller on the specified part. 

pascal ComponentResul t Musi cGetPartControl 1 er( 

Musi cComponent mc, 
long part, 

MusicController con troll erNumber ) ; 

mc Music component instance identifier returned by 

NAGetRegi steredMusi cDevi ce. 

part Part whose contioller value you want to get. 

control 1 erNumber 

On exit, the controller number. For a list of controller numbers, 
see "Controller Numbers" (page 56). 

function result A result code. 
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MusicSetPartControUer 



The MusicSetPartControUer function initializes the value of the specified 
contioUer on the specified part. 

pascal ComponentResul t Musi cSetPartControl 1 er( 
Musi cComponent mc, 
long part, 

MusicController control 1 erNumber , 
long control 1 erVal ue) ; 

mc Music component instance identifier returned by 

NAGetRegisteredMusicDevice. 

part Part whose controller value you want to set. 

control 1 erNumber 

Controller number. For valid values see "Controller Numbers" 
(page 56). 

control 1 erVal ue 

Value for controller. 

function result A result code. 



MusicSetPartSoundLocalization 



The Musi cSet Part Sound Local i zati on function passes sound localization data to a 
specified synthesizer part. 

extern pascal ComponentResul t MusicSetPartSoundLocal ization( 
Musi cComponent mc, 
long part, 
Handl e data ) ; 

mc Music component instance identifier, 

part The part to pass the data to. 

data The sound localization data. 

function result A result code. 
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Music Component Functions: Miscellaneous 

Use the functions described in this section to get and modify the master timing 
of the synthesizer, to play off line, and to allow the music component to 
perform tasks it must perform at foreground task time. 



MusicGetMasterTune 



The MusicGetMasterTune function returns a fixed-point value in semitones, 
which is the synthesizer's master tuning. 

pascal ComponentResul t MusicGetMasterTune (Musi cComponent mc); 

mc Music component instance identifier returned by 

NAGetRegi steredMusi cDevi ce. 

function result The function returns a positive value representing the 
sjmthesizer's master tuning or a negative result code. 



MusicSetMasterTune 



The Musi cSetMasterTune fimction alters the synthesizer's master tuning. 

pascal ComponentResul t Musi cSetMasterTune( 
Musi cComponent mc, 
1 ong masterTune ) ; 

mc Music component instance identifier returned by 

NAGetRegi steredMusi cDevice. 

masterTune The amount by which to transpose the entire synthesizer in 
pitch. The value is a fixed 16.16 number that allows shifts by 
fractional values. 

function result A result code. 
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MusicStartOffline 



The MusicStartOffline function informs the QuickTime music synthesizer that 
the music will not be played through the speakers. Instead, audio data will be 
sent to a fimction that will create a soimd file to be played back later. 

extern pascal ComponentResul t MusicStartOffl ine( 
Musi cComponent mc, 
unsigned long *nurtiChannel s , 
UnsignedFixed *sampl eRate , 
unsigned short *sampl eSi ze , 
MusicOffl ineDataUPP dataProc, 
long dataProcRef Con ) ; 

mc Music component instance identifier returned by 

NAGetRegisteredMusicDevice. 

numChannels Number of channels in the music sample. 1 indicates monaural; 
2 indicates stereo. 

sampl eRate The number of samples per second. 

sampl eSi ze The size of the music sample: 8-bit or 16-bit. 

dataProc A function to handle the audio data. 

dataProcRef Con 

A reference constant to pass to the dataProc function. 
function result A resiilt code. 



DISCUSSION 

You pass the MusicStartOffline function the requested values for the 
numChannel s, sampl eRate, and sampl eSi ze parameters. When the fimction 
returns, those parameters contain the actual values used. 
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MusicSetOfflineTimeTo 



The Musi cSetOf f 1 i neTi meTo function advances the synthesizer clock when the 
synthesizer is not running in real time (due to a call to Mus i cSta rtOf f 1 i ne). 

extern pascal ComponentResul t Musi cSetOf f 1 i neTimeToC 

Musi cComponent mc, 
1 ong newTi meStamp ) ; 

mc Music component instance identifier returned by 

NAGetRegi steredMusi cDevi ce. 



DISCUSSION 



MusicTask 



DISCUSSION 



newTi meStamp The number of samples to synthesize. 
function result A result code. 



Setting the time generates audio output from the synthesizer. 



Call the MusicTask function periodically to allow a music component to perform 
tasks it must perform at foreground task time. 

extern pascal ComponentResul t MusicTask (Musi cComponent mc); 

mc Music component instance identifier retiimed by 

NAGetRegi SteredMusi cDevice. 

function result A result code. 



In the case of the QuickTime music synthesizer, instnmients cannot be loaded 

from disk at interrupt time, so if the NASetlnstrumentNumberlnterruptSafe 
fxmction is called, the instrviment is loaded during the next MusicTask call. 
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Instrument Component Functions 

This section describes functions that are implemented by instrument 
components. 



InstrumentGetlnfo 



The InstrumentGetlnfo function retiirns information about all the atomic 
instnmients supported by an instnrment component. 

extern pascal ComponentResul t InstrumentGetInf o( 
Componentlnstance ci , 

long getlnstrumentlnfoFl ags , 
InstCompInf oHandl e *instInfo); 

ci The instrument component instance. You obtain the identifier 

from the Component Manager's OpenComponent fimction. See the 
chapter "Component Manager" in QuickTime 3 Reference for 
details. 

getlnstrumentlnfoFl ags 

Use these flags to specify whether you want a list of fixed 
instruments, modifiable instruments, or all instruments. See 
"Instrument Info Flags" (page 64). 

i n s 1 1 n f On exit, an instrument information list (page 83). 

function result A result code. 



InstrumentGetlnst 



The InstrumentGetlnst fimction returns an atomic instiument. 

extern pascal ComponentResul t InstrumentGetlnstC 
Componentlnstance ci , 
long instID, 

Atomi cinstrument *atomicInst, 
1 ong f 1 ags ) ; 
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ci The instrument component instance. You obtain the identifier 

from the Component Manager's OpenComponent function. See the 
chapter "Component Manager" in QuickTime 3 Reference for 
details. 

i n s 1 1 D The instrument component instrument ID from the information 

list structure retujmed by the InstrumentGetInf o function. 

atomi cinst On exit, the atomic instrument. 

flags Specifies what pieces of information about an atomic instrument 

the caller is interested in. See "Atomic Instrument Information 

Flags" (page 63). 

function result A result code. 



Instrumentlnitialize 



Used by developers of instrimient components, this is a call the instrument 
component makes to the base class instrument component to tell it how to 
interpret the instrument component resources. 

extern pascal ComponentResul t Instrumentini ti al i ze( 
Componentlnstance ci , 
long initFormat, 
void *initParams) ; 

c i An instnunent component instance. You obtain the identifier 

from the Component Manager's OpenComponent function. See the 
chapter "Component Manager" in QuickTime 3 Reference for 
details. 

initFormat Set to zero. 

initParams Set to nil. 

function result A result code. 
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InstrumentOpenComponentResFile 



The InstrumentOpenComponentResFi 1 e function opens the resoiirce file containing 
the instruments in the instrument component and makes it the current resource 
file. 

extern pascal ComponentResul t InstrumentOpenComponentResFi 1 e( 
Componentlnstance ci , 
short *resFi 1 e) ; 

c i The instrument component instance. You obtain the identifier 

from the Component Manager's OpenComponent function. See the 
chapter "Component Manager" in QuickTime 3 Reference for 
details. 

r e s F i 1 e On exit, a resource reference. 

function result A result code. 



InstrumentCloseComponentResFile 



The InstrumentCl oseComponentResFi 1 e function closes a resource file. 

extern pascal ComponentResul t InstrumentCl oseComponentResFi 1 e( 
Componentlnstance ci , 
short resFile); 

ci The instrument component instance. You obtain the identifier 

from the Component Manager's OpenComponent function. See the 
chapter "Component Manager" in QuickTime 3 Reference for 
details. 

res Fi 1 e A reference to the resource file that was returned previously by 

the InstrumentOpenComponentResFi 1 e function. 

function result A result code. 
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InstrumentGetComponentRefCon 



The InstrumentGetComponentRefCon function gets the reference constant for an 
instrument component. 

extern pascal ComponentResul t InstrumentGetComponentRefConC 

Componentlnstance ci , 
void **ref Con ) ; 

ci The instrument component instance. You obtain the identifier 

from the Component Manager's OpenComponent function. See the 
chapter "Component Manager" in QuickTime 3 Reference for 
details. 

r e f C n A reference constant. 

function result A result code. 



InstrumentSetComponentRefCon 



Use the InstrumentSetComponentRefCon function to override the Component 
Manager SetComponentRef Con function and set the instrument component's 
reference constant to a specified value. 

extern pascal ComponentResul t InstrumentSetComponentRef Con ( 
Componentlnstance ci , 
voi d *ref Con ) ; 

ci The instrument component instance. You obtain the identifier 

from the Component Manager's OpenComponent function. See the 
chapter "Component Manager" in QuickTime 3 Reference for 
details. 

r e f C n A reference constant. 

function result A result code. 
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MIDI Component Functions 

This section describes the functions that are implemented by MIDI components. 

These functions implemented by MIDI components are MIDI device drivers, 
and are called by the note allocator MIDI routines. 

Note 

NAGetMIDIPorts is the correct call for you to make. You 
should not call QTM I D I . ♦ 



QTMIDIGetMIDIPorts 



You use the QTMIDIGetMIDIPorts fimction to get two lists of MIDI ports 
supported by the specified MIDI component: a list of ports that can receive 
MIDI input and a list of ports that can send MIDI output. 

pascal ComponentResul t QTMIDIGetMIDIPorts ( 
QTMIDIComponent ci , 
QTMIDIPortListHandl e *input Ports, 
QTMIDIPortListHandle *outputPorts ) ; 

c i Specifies the instance of a MIDI component. Your software 

obtains this reference when calling the Component Manager's 
QpenComponent or QpenDefaul tComponent fimction. See the 
"Component Manager" chapter in QuickTime 3 Reference. 

inputPorts A list of the MIDI ports supported by the component that can 
receive MIDI input. 

outputPorts Alistof the MIDI ports supported by the component that can 
send MIDI output. 

DISCUSSION 

The caller of this function must dispose of the inputPorts and outputPorts 
handles. 
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QTMIDISendMIDI 



You use the QTM I D I SendM I D I function to send MIDI data to a MIDI port. 

pascal ConiponentResul t QTMIDISendMIDI ( 
QTMIDIComponent ci , 
long portlndex, 
MusicMIDIPacket *mp) ; 

c i Specifies the instance of a MIDI component. Your software 

obtains this reference when calling the Component Manager's 

OpenComponent or OpenDef aul tComponent function. See the 
"Component Manager" chapter in QuickTime 3 Reference. 

portlndex The index of the MIDI port to use for this operation. 

mp A pointer to the MIDI data packet to send. 

DISCUSSION 

The QTM I D I SendM I D I fimction can be called at interrupt time. However, the same 
interrupt level is used whenever MIDI data is sent by the specified MIDI 
component. 



QTMIDIUseReceivePort 



You use the QTMIDIUseReceivePort function to allocate a MIDI port for input or 
to release the port. 

pascal ComponentResul t QTMIDIUseReceivePort ( 

QTMIDIComponent ci , 
long portlndex, 

MusicMIDIReadHookUPP readHook, 
1 ong ref Con ) ; 

ci Specifies the instance of a MIDI component. Your software 

obtains this reference when calling the Component Manager's 
OpenComponent or OpenDef aul tComponent function. See the 
"Component Manager" chapter in QuickTime 3 Reference. 
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portlndex The index of the MIDI port to use for this operation. 

readHook A pointer to a function in your software that receives incoming 
MIDI data packets, or ni 1 to release the port. 

r e f C n A reference constant passed to the function specified by 

the readHool< parameter. 



DISCUSSION 

The MIDI component delivers only MIDI data packets that contain only a single 
status byte. 



QTMIDIUseSendPort 



You use the QTMIDIUseSendPort fimction to allocate a MIDI port for output or to 
release the port. 

pascal ComponentResul t QTMIDIUseSendPort ( 
QTMIDIComponent ci , 
long portlndex, 
1 ong i nUse) ; 



ci Specifies the instance of a MIDI component. Your software 

obtains this reference when calling the Component Manager's 
OpenComponent or QpenDefaul tComponent function. See the 
"Component Manager" chapter in QuickTime 3 Reference. 

portlndex The index of the MIDI port for this operation. 

i n U s e Specifies whether to allocate the MIDI port for output (if the 

value is 1) or to release the port (if the value is 0). 



Functions for Importing MIDI Files 

This section describes functions you use to control the importation of MIDI 
files. 
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MIDIImportGetSettings 



You use the MIDIImportGetSettings function to get settings that control the 
importation of MIDI files. 

pascal ComponentResul t MIDIImportGetSettings ( 

TextExportComponent ci , 
1 ong *setti ng ) ; 

c i Specifies the instance of the text export component used to 

import a MIDI file. Your software obtains this reference when 
calling the Component Manager's OpenComponentor 
OpenDef aul tComponent fimction. See the "Component Manager" 
chapter in QuickTime 3 Reference. 

setting Flags that control the importation of MIDI files. These flags are 

described in "MIDI File Import Flags" (page 70). 



DISCUSSION 



The flags correspond to the checkboxes in the MIDI Import Options dialog box. 



MIDIImportSetSettings 



You use the MIDIImportSetSettings function to set settings that control the 
importation of MIDI files. 

pascal ComponentResul t MIDIImportSetSettings ( 
TextExportComponent ci , 
1 ong setti ng ) ; 

ci Specifies the instance of the text export component used to 

import a MIDI file. Your software obtains this reference when 
calling the Component Manager's OpenComponent or 
OpenDefaul tComponent function. See the "Component Manager" 
chapter in QuickTime 3 Reference. 

setting Flags that control the importation of MIDI files. These flags are 

described in "MIDI File Import Flags" (page 70). 
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DISCUSSION 

The flags correspond to the checkboxes in the MIDI Import Options dialog box. 

Function Provided by the Generic Music Component 

The generic music component implements the following function that a client 
music component can call. 



MusicGenericConfigure 



You use the Musi cGeneri cConf i gure function to tell the generic music 
component what services your music component reqiiires and to point to any 
resources that are necessary 

pascal ComponentResul t MusicGenericConfigure ( 
Musi cComponent mc, 
long mode, 
1 ong flags, 
1 ong baseResID) ; 

mc Specifies the instance of the generic music component. Your 

software obtains this reference when calling the Component 
Manager's OpenComponent or OpenDef aul tComponent function. See 
the "Component Manager" chapter in QuickTime 3 Reference. 

mode Must be 0. 

flags Flags that control the importation of MIDI files. 

baseResID The resource ID of the lowest-numbered resource used by your 
music component. 

These are the possible flags for the flags parameter: 

kGenericMusicDoMIDI 

Implement normal MIDI messages for note, controllers, 

and program changes 0-127. 

l<Generi cMusi cBankO . . . kGeneri cMusi cBank32 

If kGenericMusicBankO is set, then bank changes for 
instruments numbered above 127 will be sent on controller 
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zero; if kGeneri cMusi cBank32, then on controller 32. If both 
flags are set, then the bank is sent on controller zero, and 
then a zero value is sent to controller 32 

kGeneri cMusicErsatzMIDI 

Some musical devices, such as NuBus cards, may internally 
be driven by a MIDI stream but should not appear to the 
user to be an external MIDI device. The 
kGeneri cMusi cErsatzMIDI flag instructs the generic music 
component to allocate channels appropriately and 
construct MIDI packets. The MIDI packets are always sent 
to the routine MusicDeri vedMIDISend, and never to an 
external MIDI port. 

kGeneri cMusi cCal 1 Knobs 

Specifies that your music component should receive calls to 
its routine Musi cDeri vedSetKnob for changes to global or 
part knobs. This flag should be set if your component 
implements any knobs. 

kGeneri cMusicCall Parts 

Specifies that your music component should receive calls to 
its routine MusicDerivedSetPart, in order to alter a specific 
part's polyphony or, in the case of a MIDI device, MIDI 
channel number. 

kGeneri cMusi cCal 1 Instrument 

Specifies that your music component should receive calls to 
its routine MusicDerivedSetlnstruinent, in order to set a part 
to a new instrument. This is for devices that support 
complete user-instrtiments with knob lists. If this flag is not 
set, then the generic music component calls your music 
component many times to set the value of each knob in the 
instrument. 

kGeneri cMusi cCal 1 Number 

Directs the generic music component to call your music 
component's Musi cDeri vedSetlnstrumentNumber function, 
rather than sending standard MIDI program-change and 
bank-change messages. 

kGeneri cMusicCallROMInstrument 

Allows instruments that appear to the user as instruments 
built into the synthesizer to be stored in the derived 
component's resource file, as ' ROMi ' resoiirces. The derived 
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component gets a call to Musi cDeri vedSetlnstrument when 
one of lliese instruments is requested. 



DISCUSSION 

The baseResID parameter is the lowest resource ID used by your component for 
the standard resources described above. Since the resource numbers are relative 
to this, you can include several music components in a single system extension. 

Functions Implemented by e Generic Music Component Clients 

The following fimctions are implemented by client music components of the 
generic music component. They are called by the generic music component, 
which make calls that are necessary for responding to ftinction calls made 
directly by applications. 



MusicDerivedSetKnob 



The generic music component calls your music component's 
MusicDerivedSetKnob function when any of the synthesizer's knobs are altered. 

pascal ComponentResul t Musi cDeri vedSetKnob( 
Musi cComponent mc, 
long knobType, 
long knobNumber, 
long knobValue, 
long partNumber, 
GCPart *p, 

Generi cKnobDescri pti on *gkd); 
ComponentCal 1 Now ( kMusi cDeri vedSetKnobSel ect , 24) ; 

mc Specifies the instance of the generic music component. Your 

software obtains this reference when calling the Component 
Manager's OpenComponent or OpenDefaul tComponent function. See 
the "Component Manager" chapter in QuickTime 3 Reference. 

knobType Specifies the tj^e of knob that has been altered. 
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knobNuniber Specifies the number of the knob that has been altered . 

knobValue Specifies the new value of the altered knob . 

partNuniber Specifies the number of the part whose knob has been altered. 

p A pointer to the part whose knob has been altered. 

g kd A generic knob description structure for the knob. 



DISCUSSION 

This function is called when any knob on the synthesizer is altered. It should 

look at the Part structure and the GenericKnobDescription structure and address 
the synthesizer hardware appropriately to set the new knob value. For a MIDI 
device, this means to construct a system-exclusive MIDI packet and send it to 
the MIDI routine received by the Musi cDeri vedSetMIDI call. 

These are the possible values for the knobType parameter: 

#define kGeneri cMusi cKnob 1 

#define kGeneri cMusi cInstrumentKnob 2 
#define kGeneri cMusi cDrumKnob 3 



MusicDerivedSetPart 



The generic music component calls your music component's 
MusicDerivedSetPart f imction to use the polyphony for the part specified in the 
Part structure. 

pascal ConiponentResul t MusicDerivedSetPart ( 
Musi cComponent mc, 
long partNuniber, 
GCPart *p) ; 

ComponentCal 1 Now (kMusicDerivedSetPartSelect, 8); 

mc Specifies the instance of the generic music component. Your 

software obtains this reference when calling the Component 
Manager's OpenComponent or OpenDefaul tComponent fimction. 
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partNumber Specifies the number of the part for this operation, 
p A pointer to the part for this operation. 



MusicDerivedSetlnstrument 



The generic music component calls your music component's 
MusicDerivedSetlnstrument function to get the complete instrument defined by 
the Part structure to the synthesizer. This is either by hardware addressing in 
the case of a NuBus card, or by constructing a MIDI packet for an external 
S5mthesizer. 

pascal ComponentResul t MusicDerivedSetlnstrument ( 
Musi cComponent mc, 
long partNumber, 
GCPart *p); 

ComponentCal 1 Now (l<Musi cDeri vedSetlnstrumentSel ect ,8) ; 

mc Specifies the instance of the generic music component. Your 

software obtains this reference when calling the Component 

Manager's OpenComponent or OpenDef aul tComponent function. See 
the "Component Manager" chapter in QuickTime 3 Reference. 

partNumber Specifies the number of the part for this operation. 

p A pointer to the part for this operation. 



MusicDerivedSetlnstrumentNumber 



The generic music component calls your music component's 

Musi cDeri vedSetlnstrumentNumber function to set the specified part to the 

instrument number in the Part structure. 

pascal ComponentResul t Musi cDeri vedSetlnstrumentNumber ( 
Musi cComponent mc, 
long partNumber, 
GCPart *p): 
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ComponentCal 1 Now ( kMusi cDeri vedSet Instrument NumberSel ect , 8) ; 

mc Specifies the instance of the generic music component. Your 

software obtains this reference when calling the Component 
Manager's OpenComponent or OpenDefaul tComponent function. See 
the "Component Manager" chapter in QuickTime 3 Reference. 

partNumber Specifies the number of the part for this operation. 

p A pointer to the part for this operation. 



DISCUSSION 

For a MIDI device that either only supports instruments from to 127 or that 
supports one of the standard bank-switching controller messages, this call 
should not be needed. You would set the kGenen'cMusicBankO or 
kGeneri cMusi cBank32 (or both) flags, instead. 



MusicDerivedSetMIDI 



The generic music component calls your music component's 
MusicDerivedSetMIDI function to set the MIDI channel and other MIDI settings 
for MIDI output only. It sends MIDI out to the S5mthesizer. 

pascal ComponentResul t Musi cDeri vedSetMIDI ( 
Musi cComponent mc, 
MusicMIDISendUPP midiProc, 
long refcon, 
1 ong mi di Cliannel ) ; 

ComponentCal 1 Now ( kMusi cDeri vedSetMIDI Sel ect , 12) ; 

mc Specifies the instance of the generic music component. Your 

software obtains this reference when calling the Component 
Manager's OpenComponent or OpenDefaul tComponent function. See 
the "Component Manager" chapter in QuickTime 3 Reference. 

midiProc A pointer to the function in your music component for 
performing MIDI output. 
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ref con A reference constant sent to the function specified by the 

m i d i P r c parameter. 

m i d i C h a n n e 1 Specifies the MIDI channel to use for the operation. 

DISCUSSION 

A derived component for a MIDI synthesizer receives this call soon after it is 
opened. It should store the mi di Proc, ref Con, and midi Channel in its global 
variables. When the derived component needs to communicate with the 
synthesizer, it calls the m i d i P r o c with this reference constant. The midiChannel 
variable specifies the "system channel" of the device. 



MusicDerivedStorelnstrument 



The generic music component calls your music component's 

Musi cDeri vedStorelnstrument fimction to store the specified instrimient in a 

user instrument location. 

pascal ComponentResul t MusicDerivedStorelnstrument ( 
Musi cComponent mc, 
long partNumber, 
GCPart *p, 

long i nstrumentNumber ) 

ComponentCal 1 Now ( kMusi cDeri vedStorelnstrumentSel ect ,8) ; 

mc Specifies the instance of the generic music component. Your 

software obtains this reference when calling the Component 
Manager's OpenComponent or OpenDef aul tComponent function. See 
the "Component Manager" chapter in QuickTime 3 Reference. 

partNumber Specifies the number of the part for this operation. 

p A pointer to the part for this operation. 

i nstrumentNumber 

Specifies the nvmiber of the instrument to store. 
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Result Codes 



This section lists all the residt codes returned by QmckTime music architecture 
functions. 



NOTIMPLEMENTEDMUSICOSERR -2071 

CANTSENDTOSYNTHESIZEROSERR -2072 

ILLEGALVOICEALLOCATIONOSERR -2074 

ILLEGALPARTOSERR -2075 

ILLEGALCHANNELOSERR -2076 

ILLEGALKNOBOSERR -2077 

ILLEGALKNOBVALUEOSERR -2078 

ILLEGALINSTRUMENTOSERR -2079 

ILLEGALCONTROLLEROSERR -2080 

MIDIMANAGERABSENTOSERR -2081 

SYNTHESIZERNOTRESPONDINGOSERR -2082 

SYNTHESIZEROSERR -2083 

ILLEGALNOTECHANNELOSERR -2084 



Call to a routine that is not supported by a 

particular music component. 

Attempt to use a synthesizer before it has 

been initialized, given a MIDI port to use, or 

told which slot card to use. For example, the 

MusicSetMIDIProc f xmction has not been 

called. 

Attempt to allocate more voices than a 
synthesizer supports. 
Usually indicates use of a part number 
parameter outside the range l...partcount. 
Attempt to use a MIDI channel outside the 
range 1...16. 

Attempt to use a knob index or knob ID that 
is not valid. 

Attempt to set a knob outside its allowable 
range, as specified in its knob description 
structure. 

Attempt to use an instrument or sound that is 
not available or there is some other problem 
with the instrument, such as a bad instrument 
number. 

Attempt to get or set a controller that is 
outside the allowable controller nvimber range 
or is not recognized by this particular music 
component. 

Attempt to use MIDI Manager for a 
synthesizer when the MIDI Manager is not 
installed. 

Various hardware problems with a 

synthesizer. 

Software problem with a synthesizer. 
Attempt to use a note charmel that is not 
initialized or is otherwise errant. 
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NOTECHANNELNOTALLOCATEDOSERR -2085 
TUNEPLAYERFULLOSERR -2086 

TUNEPARSEOSERR -2087 



It was not possible to allocate a note channel. 
Attempt to queue up more tune segments 
(with TuneQueue) than allowed. 
TuneSetHeader or TuneQueue encountered 
illegal tune sequence data. 
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Table A-1 



General MIDI instrument numbers 



Number 


Instrument 


Number 


Instrument 


1 


Acoustic Grand Piano 


65 


Soprano Sax 


2 


Bright Acoustic Piano 


66 


Alto Sax 


3 


Electric Grand Piano 


67 


Tenor Sax 


4 


Honky-tonk Piano 


68 


Baritone Sax 


5 


Rhodes Piano 


69 


Oboe 


6 


Chorused Piano 


70 


English Horn 


7 


Harpsichord 


71 


Bassoon 


8 


Clavinet 


72 


Clarinet 


9 


Celesta 


73 


Piccolo 


10 


Glockenspiel 


74 


Flute 


11 


Music Box 


75 


Recorder 


12 


Vibraphone 


76 


Pan Flute 


13 


Marimba 


77 


Bottle Blow 


14 


Xylophone 


78 


Shakuhachi 


15 


Tubular bells 


79 


Whistle 


16 


Dulcimer 


80 


Ocarina 


17 


Draw Organ 


81 


Square Lead 
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Number 


Instrument 


Number 


Instrument 


18 


Percussive Organ 


82 


Saw Lead 


19 


Rock Organ 


83 


Calliope 


20 


Chiirch Organ 


84 


Chiffer 


21 


Reed Organ 


85 


Synth Lead 5 


22 


Accordion 


86 


Synth Lead 6 


23 


Harmonica 


87 


Synth Lead 7 


24 


Tango Accordion 


88 


Synth Lead 8 


25 


Acoustic Nylon Giiitar 


89 


Synth Pad 1 


26 


Acoustic Steel Guitar 


90 


Synth Pad 2 


27 


Electric Jazz Guitar 


91 


Synth Pad 3 


28 


Electric Clean Guitar 


92 


Synth Pad 4 


29 


Electric Guitar Muted 


93 


Synth Pad 5 


30 


Overdriven Guitar 


94 


Synth Pad 6 


31 


Distortion Guitar 


95 


Synth Pad 7 


32 


Guitar Harmonics 


96 


Synth Pad 8 


33 


Wood Bass 


97 


Ice Rain 


34 


Electric Bass Fingered 


98 


Soundtracks 


35 


Electric Bass Picked 


99 


Crystal 


36 


Fretless Bass 


100 


Atmosphere 


37 


Slap Bass 1 


101 


Bright 


38 


Slap Bass 2 


102 


Goblin 


39 


S5mth Bass 1 


103 


Echoes 


40 


S5mth Bass 2 


104 


Space 


41 


Violin 


105 


Sitar 


42 


Viola 


106 


Banjo 
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Table A-1 General MIDI Instrument numbers 



Number 


Instrument 


Number 


Instrument 


43 


CeUo 


107 


Shamisen 


44 


Contrabass 


108 


Koto 


45 


Tremolo Strings 


109 


KaUmba 


46 


Pizzicato Strings 


110 


Bagpipe 


47 


Orchestral Harp 


111 


Fiddle 


48 


Timpani 


112 


Shanai 


49 


Acoustic String 
Ensemble 1 


113 


Tinkle Bell 


50 


Acoustic String 
Ensemble 2 


114 


Agogo 


51 


Synth Strings 1 


115 


Steel Drums 


52 


Synth Strings 2 


116 


Woodblock 


53 


Aah Choir 


117 


Taiko Drum 


54 


Ooh Choir 


118 


Melodic Tom 


55 


Synvox 


119 


Synth Tom 


56 


Orchestra Hit 


120 


Reverse Cymbal 


57 


Trumpet 


121 


Guitar Fret Noise 


58 


Trombone 


122 


Breath Noise 


59 


Tuba 


123 


Seashore 


60 


Muted Trumpet 


124 


Bird Tweet 


61 


French Horn 


125 


Telephone Ring 


62 


Brass Section 


126 


Helicopter 


63 


Synth Brass 1 


127 


Applause 


64 


Synth Brass 2 


128 


Gunshot 
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General MIDI Drum Kit Numbers 



Table A-2 


General MIDI drum kit numbers 




35 


Acoustic Bass Drum 


51 


Ride Cymbal 1 


36 


Bass Drum 1 


52 


Chinese Cymbal 


37 


Side Stick 


53 


Ride Bell 


38 


Acoustic Snare 


54 


Tambourine 


39 


Hand Clap 


55 


Splash Cymbal 


40 


Electric Snare 


56 


Cowbell 


41 


Lo Floor Tom 


57 


Crash Cymbal 2 


42 


Closed Hi Hat 


58 


Vibraslap 


43 


Hi Floor Tom 


59 


Ride Cymbal 2 


44 


Pedal Hi Hat 


60 


Hi Bongo 


45 


Lo Tom Tom 


61 


Low Bongo 


46 


Open Hi Hat 


62 


Mute Hi Conga 


47 


Low Mid Tom Tom 


63 


Open Hi Conga 


48 


Hi Mid Tom Tom 


64 


Low Conga 


49 


Crash Cymbal 1 


65 


Hi Timbale 


50 


Hi Tom Tom 


66 


Lo Timbale 
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General MIDI Kit Names 



Table A-3 General MIDI kit names 

1 Dry Set 

9 Room Set 

19 Power Set 

25 Electronic Set 

33 Jazz Set 

41 Brush Set 

65-112 User Area 

128 Default 



General MIDI Kit Names 



179 



APPENDIX 

General MIDI Reference 



180 



General MIDI Kit Names 



